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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_cli
-Version: 0.0.17
+Version: 0.0.19
 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
@@ -48,7 +48,7 @@ smpy create-module my_feature         # scaffold a publishable module package
 smpy create-host bare-host            # scaffold a bare host (no opinionated wiring)
 ```
 
-Built-in commands: `smpy new`, `smpy create-host`, `smpy create-module`.
+Built-in commands: `smpy new`, `smpy create-host`, `smpy create-module`, `smpy package-update`, and `smpy skills {list,add,update}`.
 
 When other framework packages are installed, they contribute additional subcommands via the `simple_module_cli.cli_plugins` entry-point group:
 

{simple_module_cli-0.0.17 → simple_module_cli-0.0.19}/README.md

@@ -23,7 +23,7 @@ smpy create-module my_feature         # scaffold a publishable module package
 smpy create-host bare-host            # scaffold a bare host (no opinionated wiring)
 ```
 
-Built-in commands: `smpy new`, `smpy create-host`, `smpy create-module`.
+Built-in commands: `smpy new`, `smpy create-host`, `smpy create-module`, `smpy package-update`, and `smpy skills {list,add,update}`.
 
 When other framework packages are installed, they contribute additional subcommands via the `simple_module_cli.cli_plugins` entry-point group:
 

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

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

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

@@ -17,8 +17,6 @@ import json as _json
 import secrets as _secrets
 import shutil as _shutil
 from collections.abc import Sequence
-from importlib.metadata import PackageNotFoundError
-from importlib.metadata import version as _pkg_version
 from pathlib import Path
 from typing import Any
 
@@ -32,6 +30,7 @@ from simple_module_cli.scaffolding import (
     create_host,
     create_module,
     create_workspace,
+    resolve_framework_version,
 )
 
 __all__ = ["create_app_project"]
@@ -40,30 +39,21 @@ _SAMPLE_MODULE_NAME = "hello"
 _SAMPLE_MODULE_PKG = _module_to_pypi_name(_SAMPLE_MODULE_NAME)
 
 
-def _resolve_framework_version() -> str:
-    """Resolve the framework version to pin scaffolded apps against.
-
-    The CLI ships in lockstep with the rest of the framework (one
-    ``bump_version.py`` rewrites every ``pyproject.toml`` in the repo), so
-    its own installed version is the source of truth. Falling back to a
-    placeholder lets editable installs without dist-info still scaffold —
-    but that path should never be reached in a release wheel.
-    """
-    try:
-        return _pkg_version("simple_module_cli")
-    except PackageNotFoundError:
-        return "0.0.0"
-
-
-_FRAMEWORK_VERSION = _resolve_framework_version()
+_FRAMEWORK_VERSION = resolve_framework_version()
 
 # Pin ``simple_module_cli`` as a dev dep so ``uv run smpy`` resolves to the
 # project venv. The global ``uv tool`` install runs in its own isolated venv
-# that can't see the project's plugin entry points (issue #134).
+# that can't see the project's plugin entry points (issue #134). The lint /
+# test tooling (ruff, ty, pytest-*) backs the generated `make lint`/`make
+# test` targets so a fresh app can run its own quality gates.
 _APP_PY_DEV_DEPS = [
     f"simple_module_test=={_FRAMEWORK_VERSION}",
     f"simple_module_cli=={_FRAMEWORK_VERSION}",
     "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-playwright>=0.7.2",
+    "ruff>=0.8",
+    "ty>=0.0.29",
 ]
 
 _APP_NPM_DEPS = {
@@ -120,7 +110,12 @@ def create_app_project(
     preserved: list[Path] = []
     if not flat:
         preserved.extend(
-            create_workspace(target, name=name, preserve_existing=SAFE_PRESERVED_NAMES)
+            create_workspace(
+                target,
+                name=name,
+                framework_version=_FRAMEWORK_VERSION,
+                preserve_existing=SAFE_PRESERVED_NAMES,
+            )
         )
     preserved.extend(
         create_host(
@@ -195,11 +190,13 @@ def _scaffold_sample_module(target: Path) -> None:
     sample_dest = target / "modules" / _SAMPLE_MODULE_NAME
     if sample_dest.exists():
         return
-    create_module(sample_dest, name=_SAMPLE_MODULE_NAME)
+    # 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")
-    _pin_sample_module_deps(sample_dest)
     _seed_static_dist_placeholder(sample_dest / _SAMPLE_MODULE_NAME / "static" / "dist")
 
 
@@ -210,35 +207,6 @@ def _seed_static_dist_placeholder(static_dist: Path) -> None:
     (static_dist / ".gitkeep").touch()
 
 
-def _pin_sample_module_deps(sample_dest: Path) -> None:
-    """Replace the module template's future-API range pins with exact pins.
-
-    The shared ``smpy create-module`` template ships ``>=1.0,<2.0`` against the
-    framework's eventual stable line, but the workspace-bundled sample has to
-    resolve against whatever the framework version actually is today (``==X``
-    in pre-1.0). Without rewriting, ``uv sync`` can't satisfy the workspace.
-    """
-    import tomlkit
-
-    pyproject = sample_dest / "pyproject.toml"
-    doc = tomlkit.parse(pyproject.read_text(encoding="utf-8"))
-    project = doc.setdefault("project", tomlkit.table())
-    project["dependencies"] = [_pin_or_keep(dep) for dep in project.get("dependencies", [])]
-    optional = project.get("optional-dependencies")
-    if optional is not None:
-        for extra, deps in list(optional.items()):
-            optional[extra] = [_pin_or_keep(dep) for dep in deps]
-    pyproject.write_text(tomlkit.dumps(doc), encoding="utf-8")
-
-
-def _pin_or_keep(dep: str) -> str:
-    """Pin a ``simple_module_*`` requirement to the framework version; pass through otherwise."""
-    pkg = dep.split(">=", 1)[0].split("==", 1)[0].split("<", 1)[0].strip()
-    if pkg.startswith(("simple_module_", "simple-module-")):
-        return f"{pkg}=={_FRAMEWORK_VERSION}"
-    return dep
-
-
 def _db_url(db: str, slug: str, *, flat: bool) -> str:
     if db == "postgres":
         return f"postgresql+asyncpg://postgres:postgres@localhost:5432/{slug}"

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

@@ -23,6 +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.skills_cmd import app as skills_app
 
 app = typer.Typer(
@@ -55,7 +56,17 @@ def create_host(
     target = dest or Path.cwd() / name
     selected = [m.strip() for m in modules.split(",") if m.strip()]
     try:
-        _create_host(target, name=name, modules=selected)
+        # Pin the host's framework + module deps to the installed framework
+        # version so the generated host's first `uv sync` resolves (the
+        # template's >=1.0,<2.0 / >=0.1,<1.0 ranges don't exist pre-1.0). The
+        # workspace `smpy new` path rewrites these via _rewrite_pyproject, but
+        # standalone create-host never did — see GH #206.
+        _create_host(
+            target,
+            name=name,
+            modules=selected,
+            framework_version=resolve_framework_version(),
+        )
     except FileExistsError as exc:
         typer.echo(f"ERROR: {exc}", err=True)
         raise typer.Exit(code=1) from exc
@@ -68,7 +79,7 @@ def create_host(
     typer.echo("  uv sync")
     typer.echo("  cp .env.example .env")
     typer.echo('  alembic revision --autogenerate -m "initial schema"')
-    typer.echo("  alembic upgrade head")
+    typer.echo("  alembic upgrade heads")
     typer.echo("  python main.py")
 
 
@@ -85,7 +96,10 @@ def create_module(
     package = slug.replace("-", "_")
     target = dest or Path.cwd() / f"simple_module_{package}"
     try:
-        _create_module(target, name=name)
+        # 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())
     except FileExistsError as exc:
         typer.echo(f"ERROR: {exc}", err=True)
         raise typer.Exit(code=1) from exc

{simple_module_cli-0.0.17 → simple_module_cli-0.0.19}/simple_module_cli/new.py

@@ -164,7 +164,9 @@ def new_project(
             return
 
     _bootstrap_initial_migration(host_dir)
-    subprocess.run([*_ALEMBIC, "upgrade", "head"], cwd=host_dir, check=False)
+    # `heads` (plural) applies every per-module branch head; `head` (singular)
+    # errors once a second module ships its own migration branch label.
+    subprocess.run([*_ALEMBIC, "upgrade", "heads"], cwd=host_dir, check=False)
     typer.echo("\nSetup complete. Run `make dev` in the new directory.")
     if "background_tasks" in resolved:
         typer.echo("For background jobs, also run: docker compose up -d redis worker beat")

simple_module_cli-0.0.19/simple_module_cli/pins.py

@@ -0,0 +1,66 @@
+"""Resolve and pin the framework version that scaffolded apps depend on.
+
+Kept separate from :mod:`simple_module_cli.scaffolding` (template
+materialization) because version resolution + dependency pinning is its own
+concern: the scaffolders, ``cli`` commands, and ``app_project`` all reach for
+it independently. The module templates ship forward-looking ``simple_module_*``
+ranges (``>=1.0,<2.0`` / ``>=0.1,<1.0``) against the framework's eventual stable
+line, but the published distributions are pre-1.0 (``0.0.x``), so those ranges
+resolve to nothing on PyPI. Rewriting them to an exact ``==`` pin lets a freshly
+scaffolded app/module resolve against the framework version that created it.
+See GH #195 / #206.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resolve_framework_version() -> str:
+    """Resolve the framework version that scaffolded apps should pin against.
+
+    The CLI ships in lockstep with the rest of the framework (one
+    ``bump_version.py`` rewrites every ``pyproject.toml``), so its own
+    installed distribution version is the source of truth. Falls back to a
+    placeholder for editable installs lacking dist-info — never reached from a
+    release wheel.
+    """
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as pkg_version
+
+    try:
+        return pkg_version("simple_module_cli")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+def _pin_one(dep: str, version: str) -> str:
+    """Pin a single ``simple_module_*`` requirement to ``==version``; else pass through."""
+    pkg = dep.split(">=", 1)[0].split("==", 1)[0].split("<", 1)[0].strip()
+    if pkg.startswith(("simple_module_", "simple-module-")):
+        return f"{pkg}=={version}"
+    return dep
+
+
+def pin_framework_deps(pyproject_path: Path, version: str) -> None:
+    """Pin every ``simple_module_*`` requirement in a pyproject to ``==version``.
+
+    Rewrites both ``dependencies`` and every ``optional-dependencies`` extra
+    (the module template's ``dev`` extra pins ``simple_module_test``). Used by
+    ``create_module`` and ``create_host`` so a freshly scaffolded package
+    resolves against the framework version that created it. See GH #195 / #206.
+    """
+    import tomlkit
+
+    doc = tomlkit.parse(pyproject_path.read_text(encoding="utf-8"))
+    project = doc.get("project")
+    if project is None:
+        return
+    deps = project.get("dependencies")
+    if deps is not None:
+        project["dependencies"] = [_pin_one(dep, version) for dep in deps]
+    optional = project.get("optional-dependencies")
+    if optional is not None:
+        for extra, items in list(optional.items()):
+            optional[extra] = [_pin_one(dep, version) for dep in items]
+    pyproject_path.write_text(tomlkit.dumps(doc), encoding="utf-8")

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

@@ -28,11 +28,17 @@ from simple_module_cli.case import (
     validate_scaffold_name,
 )
 
+# Re-exported so the scaffolders and their long-standing callers keep importing
+# version pinning from one place; the implementations live in pins.py.
+from simple_module_cli.pins import pin_framework_deps, resolve_framework_version
+
 __all__ = [
     "SAFE_PRESERVED_NAMES",
     "create_host",
     "create_module",
     "create_workspace",
+    "pin_framework_deps",
+    "resolve_framework_version",
 ]
 
 logger = logging.getLogger(__name__)
@@ -55,6 +61,17 @@ def _module_to_pypi_name(name: str) -> str:
     return f"simple_module_{name.lower()}"
 
 
+def _should_pin_framework_version(version: str | None) -> bool:
+    """Whether ``version`` is a concrete pin rather than a skip sentinel.
+
+    Both scaffolders skip pinning for ``None`` (a library caller that wants the
+    template's ranges kept verbatim) and ``"*"`` (the npm-wildcard default,
+    which would otherwise render the invalid PEP 508 specifier ``==*``). One
+    rule, so the two paths can't drift. See GH #195 / #206.
+    """
+    return bool(version) and version != "*"
+
+
 def _iter_template_files(template_root: Path):
     """Yield every file under ``template_root``. Skips ``_optional/`` paths."""
     for path in template_root.rglob("*"):
@@ -124,15 +141,20 @@ def create_workspace(
     dest: Path,
     name: str,
     template_root: Path | None = None,
+    framework_version: str = "*",
     *,
     preserve_existing: frozenset[str] = frozenset(),
 ) -> list[Path]:
     """Materialize the workspace-root shell at ``dest``; return preserved paths.
 
-    Lays down the top-level ``pyproject.toml`` (uv workspace), ``package.json``
-    (npm workspace), ``Makefile`` (delegates to host), ``.env.example``,
-    ``.gitignore``, and ``README.md``. Does NOT create the host or any
-    modules — those go under ``dest/host`` and ``dest/modules/`` afterwards.
+    Lays down the top-level ``pyproject.toml`` (uv workspace + dev tooling for
+    ``make test``/``lint``), ``package.json`` (npm workspace), ``Makefile``
+    (delegates to host), ``.env.example``, ``.gitignore``, and ``README.md``.
+    Does NOT create the host or any modules — those go under ``dest/host`` and
+    ``dest/modules/`` afterwards.
+
+    ``framework_version`` pins ``simple_module_test`` in the root dev group;
+    defaults to ``"*"`` for callers that don't need an exact pin.
 
     ``preserve_existing`` lists top-level entry names that may already exist
     in ``dest``; the scaffold's copy is skipped and the preserved path is
@@ -147,6 +169,7 @@ def create_workspace(
         {
             "{{HOST_NAME}}": validate_scaffold_name(name),
             "{{HOST_PYPI_NAME}}": to_kebab_case(name),
+            "{{FRAMEWORK_VERSION}}": framework_version,
         },
         preserve_existing=preserve_existing,
     )
@@ -181,6 +204,12 @@ def create_host(
         },
         preserve_existing=preserve_existing,
     )
+    # Pin every simple_module_* host dep (framework packages *and* selected
+    # bundled modules) to the lockstep version so the host's first `uv sync`
+    # resolves — the template's >=1.0,<2.0 / >=0.1,<1.0 ranges match nothing
+    # against pre-1.0 dists. See GH #206.
+    if _should_pin_framework_version(framework_version):
+        pin_framework_deps(dest / "pyproject.toml", framework_version)
     logger.info(
         "Scaffolded host '%s' at %s (modules: %s)", name, dest, ", ".join(modules) or "<none>"
     )
@@ -191,7 +220,17 @@ def create_module(
     dest: Path,
     name: str,
     template_root: Path | None = None,
+    *,
+    framework_version: str | None = None,
 ) -> Path:
+    """Scaffold a module package at ``dest``.
+
+    When ``framework_version`` is a concrete version, the template's
+    forward-looking ``simple_module_*`` ranges are rewritten to an exact pin so
+    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.
+    """
     dest = Path(dest)
     existed_before = dest.exists()
     _require_empty_dest(dest)
@@ -210,6 +249,8 @@ def create_module(
             },
             path_rewrites={_PACKAGE_PATH_TOKEN: package_name},
         )
+        if _should_pin_framework_version(framework_version):
+            pin_framework_deps(dest / "pyproject.toml", framework_version)
     except Exception:
         # Rollback so a half-scaffolded directory doesn't leave the user
         # with an unparseable Python package and the impression that a

{simple_module_cli-0.0.17 → simple_module_cli-0.0.19}/simple_module_cli/skills/README.md

@@ -47,7 +47,7 @@ The CLI is [vercel-labs/skills](https://github.com/vercel-labs/skills); see its
 | [simple-module-locales](./simple-module-locales/SKILL.md) | Adding or debugging i18n in a module — `locale_dirs()`, namespaces, CLDR plurals, the Zod-in-hook rule |
 | [simple-module-registries](./simple-module-registries/SKILL.md) | Contributing menu items, permissions, feature flags, or events from a module |
 | [simple-module-testing](./simple-module-testing/SKILL.md) | Writing pytest tests — picking the right fixture (`db_session` / `app` / `authenticated_client`), single-test runs, e2e |
-| [simple-module-doctor](./simple-module-doctor/SKILL.md) | Interpreting a diagnostic code (`SM001`–`SM018`) printed at boot |
+| [simple-module-doctor](./simple-module-doctor/SKILL.md) | Interpreting a diagnostic code (`SM001`–`SM021`) printed at boot |
 
 The skills are designed to stand alone — install them into any host or module-package project and they'll work without needing access to the framework's source repo.
 

{simple_module_cli-0.0.17 → simple_module_cli-0.0.19}/simple_module_cli/skills/simple-module-cli/SKILL.md

@@ -5,7 +5,7 @@ description: Use when invoking the `smpy` CLI for a simple_module_python project
 
 # 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 four kinds of operations: scaffolding new things, project-time helpers for the host, admin shortcuts for the bundled modules, and installing the bundled agent skills.
+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.
 
 ## Top-level commands
 
@@ -14,6 +14,7 @@ The `smpy` command is provided by `simple_module_cli` (installed as a dep of `si
 | `smpy new <name>` | Greenfield: scaffold a complete app (host + selected modules) in one shot, with an interactive wizard for DB / tenancy / module preset |
 | `smpy create-host <name>` | You want just a bare host project; you'll add modules later by `pip install`-ing them |
 | `smpy create-module <name>` | You're authoring a publishable module package (separate repo, distributed via PyPI) |
+| `smpy package-update` | Bump every `simple_module_*` / `simple-module-*` dependency in `pyproject.toml` to its latest non-yanked PyPI release (workspace/path/git/URL sources are left untouched) |
 | `smpy skills …` | Install / update the bundled agent-skill packs into a project (`add`, `list`, `update`) |
 | `smpy host …` | Project-time helpers run from inside a host directory (page manifest, JS dep sync) |
 | `smpy settings …` | Settings-module admin — currently `import-from-env` |
@@ -47,7 +48,7 @@ smpy new MyApp --no-install
 | `full` | every module in the catalog |
 | `custom` | interactive — pick each module yes/no |
 
-`--with` accepts a comma-separated list of catalog keys (`auth, users, permissions, products, 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.
 
 **Options summary:**
 

{simple_module_cli-0.0.17 → simple_module_cli-0.0.19}/simple_module_cli/skills/simple-module-creating/SKILL.md

@@ -68,7 +68,7 @@ class OrdersModule(ModuleBase):
     )
 ```
 
-`ModuleMeta.name` is load-bearing in three places: the Postgres schema name, the SQLite `__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).
+`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.
 

{simple_module_cli-0.0.17 → simple_module_cli-0.0.19}/simple_module_cli/skills/simple-module-database/SKILL.md

@@ -18,26 +18,14 @@ from simple_module_db.mixins import AuditMixin
 Base = create_module_base("orders")
 
 class Order(Base, AuditMixin, table=True):
-    __tablename__ = "orders_order"   # SQLite-safe prefix; required (see below)
+    __tablename__ = "orders_order"   # module-name prefix; required
     id: int | None = Field(default=None, primary_key=True)
     name: str = Field(max_length=200)
 ```
 
-The provider is auto-detected from `SM_DATABASE_URL`. Pin it explicitly only in tests:
+## Table naming
 
-```python
-from simple_module_db.base import create_module_base, DatabaseProvider
-Base = create_module_base("orders", provider=DatabaseProvider.SQLITE)
-```
-
-## Postgres vs SQLite — the same code, different physical layout
-
-| Provider | Physical placement | Required convention |
-|---|---|---|
-| **PostgreSQL** | One **schema** per module (`orders.order`, `users.user`). Created automatically. | Set `__tablename__` to a name unique within the module. |
-| **SQLite** | Single schema. Cross-module name collisions break things. | Prefix `__tablename__` with the module name (`orders_order`). |
-
-Always include the module-name prefix in `__tablename__`. It's redundant on Postgres (the schema already namespaces it) and **required** on SQLite. Code that runs in CI on SQLite and prod on Postgres needs both — pick the prefix.
+All modules — on Postgres and SQLite alike — share the host's single schema. Cross-module name collisions break things, so `__tablename__` must be prefixed with the module name (e.g. `orders_order`, `users_user`). The framework does not enforce the prefix; it's a convention the migrations and diagnostics rely on.
 
 ## Mixins
 

{simple_module_cli-0.0.17 → simple_module_cli-0.0.19}/simple_module_cli/skills/simple-module-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: simple-module-doctor
-description: Use when interpreting a simple_module_python diagnostic code (SM001–SM018) printed at boot or by the diagnostics runner — what the code means, whether it's blocking, and the concrete fix. Triggers on any "SMnnn" code in logs, "InvalidModuleError", "module silently doesn't load", or "production failed boot".
+description: Use when interpreting a simple_module_python diagnostic code (SM001–SM021) printed at boot or by the diagnostics runner — what the code means, whether it's blocking, and the concrete fix. Triggers on any "SMnnn" code in logs, "InvalidModuleError", "module silently doesn't load", or "production failed boot".
 ---
 
 # simple_module_python: diagnostics
@@ -17,7 +17,7 @@ You can also call `run_diagnostics(...)` from `simple_module_core` programmatica
 | **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` (Postgres-schema / SQLite-prefix collision) | Rename one module's `meta.name` |
+| **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` |
 | **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 |
@@ -27,9 +27,12 @@ You can also call `run_diagnostics(...)` from `simple_module_core` programmatica
 | **SM015** | WARNING | A non-default locale has keys *not* present in the default | Remove dead keys from the non-default file or add them to default |
 | **SM016** | ERROR | A locale JSON file is invalid or contains non-string leaves | Fix the JSON; only string leaves are allowed (interpolation is `{name}` placeholders) |
 | **SM017** | WARNING | A module ships `.tsx` pages but is missing `package.json` / `tsconfig.json` | Add the JS workspace files so the host's frontend toolchain can resolve module imports |
-| **SM018** | WARNING | An Inertia page calls `router.{post,patch,put,delete}()` targeting `/api/*` | Use plain `fetch()` for JSON endpoints; Inertia's client expects an Inertia response, not JSON |
+| **SM018** | WARNING | An Inertia page calls `router.{post,patch,put,delete}()` targeting `/api/*` | Point the call at a view endpoint that returns `RedirectResponse(..., status_code=303)`, or use plain `fetch()` for the JSON endpoint; Inertia's client expects an Inertia response, not JSON |
+| **SM019** | WARNING | A module registers view routes (non-empty `view_prefix` + overrides `register_routes`) but overrides neither `register_menu_items` nor `register_permissions` — its pages exist with no sidebar entry and no role-editor visibility | Add `register_menu_items()` (sidebar) or `register_permissions()` (role editor), or clear `view_prefix` if the module is API-only |
+| **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` are reserved/retired — don't try to look them up. Output format is one line per finding, e.g. `[SM009] ERROR: <subject>`.
+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>`.
 
 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.
 

{simple_module_cli-0.0.17 → simple_module_cli-0.0.19}/simple_module_cli/skills/simple-module-registries/SKILL.md

@@ -47,7 +47,7 @@ class OrdersModule(ModuleBase):
 
 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.
 
-To check inside an endpoint, depend on the `RequireAnyPermissionDep` / `RequireAllPermissionsDep` dependencies (see auth/users), not by reading the registry by hand.
+To check inside an endpoint, depend on `RequiresPermission("<module>.<action>")` (from `simple_module_hosting.permissions`), not by reading the registry by hand. The dependency handles wildcard expansion and the 401-vs-403 distinction.
 
 ## Feature flags — `register_feature_flags(registry: FeatureFlagRegistry)`
 
@@ -132,7 +132,7 @@ 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.
-- **Raw permission strings in endpoints (`request.state.user.permissions`).** Use `RequireAnyPermissionDep` / `RequireAllPermissionsDep`. The dependency handles wildcard expansion and 401 vs 403 distinction.
+- **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.
 - **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.

simple_module_cli-0.0.19/simple_module_cli/templates/host/Makefile

@@ -0,0 +1,55 @@
+.PHONY: install dev dev-api dev-ui build test test-py test-js lint doctor migrate migration gen-pages sync-js-deps
+
+install:
+	uv sync
+	cd client_app && npm install
+	$(MAKE) sync-js-deps
+
+dev: gen-pages
+	@echo "Starting API and UI dev servers..."
+	$(MAKE) -j2 dev-api dev-ui
+
+dev-api:
+	uv run uvicorn main:app --reload --port 8000
+
+dev-ui:
+	cd client_app && npm run dev
+
+build:
+	cd client_app && npm run build
+
+# Testing
+test: test-py test-js
+
+test-py:
+	uv run pytest
+
+# --if-present is a no-op until you add a "test" script (e.g. vitest) to package.json.
+test-js:
+	cd client_app && npm run test --if-present
+
+# Lint + typecheck (Python). Mirrors the framework's own quality gate.
+lint:
+	uv run ruff format --check .
+	uv run ruff check .
+	uv run ty check
+
+# Module diagnostics — the same checks that run at prod boot (orphan pages,
+# coupling violations, migration drift, locale issues).
+doctor:
+	uv run python -m simple_module_core
+
+gen-pages:
+	uv run python -m simple_module_hosting gen-pages --host-dir=client_app
+
+sync-js-deps:
+	uv run python -m simple_module_hosting sync-js-deps --host-client-app=client_app
+
+# `upgrade heads` (plural) applies every per-module branch head; `upgrade head`
+# (singular) errors once a second module adds its own migration branch label.
+migrate:
+	uv run alembic upgrade heads
+
+migration:
+	@test -n "$(msg)" || (echo 'Usage: make migration msg="describe the change"' && exit 1)
+	uv run alembic revision --autogenerate -m "$(msg)"

simple_module_cli-0.0.19/simple_module_cli/templates/host/main.py

@@ -0,0 +1,59 @@
+"""Host application entry point.
+
+This file was generated by `smpy create-host`. Modules are discovered at boot
+via entry_points; add them to this host's pyproject.toml to install them.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+from simple_module_core.dotenv import load_dotenv_into_environ
+
+# Pin this host directory on ``sys.path`` as an ABSOLUTE path *before* the
+# chdir below, so ``from routes import ...`` resolves no matter what the cwd
+# is. The scaffolded Makefile launches the app as ``cd host && uvicorn
+# main:app``; uvicorn puts the launch cwd on ``sys.path`` as the empty string
+# ``''`` (resolved lazily against the *current* cwd). Once we chdir to the
+# repo root, that ``''`` entry points at the wrong directory and the sibling
+# ``routes`` module is no longer importable — and the ``--reload`` subprocess
+# re-imports via the same path, so it breaks there too. See GH #194.
+_HOST_DIR = Path(__file__).resolve().parent
+_REPO_ROOT = _HOST_DIR.parent
+if str(_HOST_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOST_DIR))
+
+# Resolve the workspace root from this file's location so the web process
+# behaves the same regardless of where uvicorn was launched (``uv run
+# --project host`` or a wheel deployment may run from elsewhere). chdir up
+# front so cwd-relative paths in ``.env`` (e.g.
+# ``sqlite+aiosqlite:///./host/app.db``) resolve consistently; load ``.env``
+# into ``os.environ`` so framework code reading ``os.environ.get("SM_…")``
+# directly sees the same values pydantic does.
+os.chdir(_REPO_ROOT)
+load_dotenv_into_environ(_REPO_ROOT / ".env")
+
+from simple_module_hosting import Settings, create_app  # noqa: E402
+from simple_module_hosting.logging import setup_logging  # noqa: E402
+
+from routes import router as host_router  # noqa: E402
+
+settings = Settings()
+
+setup_logging(
+    level=settings.log_level,
+    json_format=settings.log_format == "json",
+)
+
+app = create_app(settings)
+app.include_router(host_router)
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(
+        "main:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=settings.is_development,
+    )