simple-module-cli 0.0.35__tar.gz → 0.0.37__tar.gz

{simple_module_cli-0.0.35 → simple_module_cli-0.0.37}/.gitignore

@@ -64,3 +64,4 @@ host/client_app/.playwright-cli/*
 .superpowers/
 .qa/
 .verify/
+/openapi.json

{simple_module_cli-0.0.35 → simple_module_cli-0.0.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_cli
-Version: 0.0.35
+Version: 0.0.37
 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.35 → simple_module_cli-0.0.37}/pyproject.toml

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

{simple_module_cli-0.0.35 → simple_module_cli-0.0.37}/simple_module_cli/_env.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__all__ = ["set_env_key"]
+__all__ = ["env_values", "set_env_key"]
 
 
 def set_env_key(text: str, key: str, value: str) -> str:
@@ -10,3 +10,10 @@ def set_env_key(text: str, key: str, value: str) -> str:
     lines = [ln for ln in text.splitlines() if not ln.startswith(f"{key}=")]
     lines.append(f"{key}={value}")
     return "\n".join(lines) + "\n"
+
+
+def env_values(text: str) -> dict[str, str]:
+    """Parse the ``KEY=VALUE`` lines of an env-style file body (comments skipped)."""
+    lines = text.splitlines()
+    pairs = (ln.split("=", 1) for ln in lines if "=" in ln and not ln.lstrip().startswith("#"))
+    return {key.strip(): value for key, value in pairs}

simple_module_cli-0.0.37/simple_module_cli/_local_env.py

@@ -0,0 +1,83 @@
+"""Split a new app's env file into a committed template and a local ``.env``.
+
+``.env.example`` is committed, so it only ever carries placeholders. The
+secrets ``smpy new`` generates go to ``.env``, which every scaffold's
+``.gitignore`` excludes (GH #441). An existing ``.env`` is never overwritten:
+only keys it does not define yet are added.
+"""
+
+from __future__ import annotations
+
+import secrets
+from collections.abc import Iterable
+from pathlib import Path
+
+from simple_module_cli._env import env_values, set_env_key
+
+__all__ = ["add_postgres_password_placeholder", "comment_out_env_key", "write_local_env"]
+
+_PG_PASSWORD_NOTE = (
+    "# Compose puts this into SM_DATABASE_URL unencoded: use only URL-safe\n"
+    "# characters (letters, digits, - _ . ~). `make docker-up` rejects others (GH #472).\n"
+)
+
+_SECRET_NOTE = (
+    "# Secrets — `smpy new` generated these into .env (gitignored); keep them\n"
+    "# out of this committed file. Set real values wherever you deploy."
+)
+
+
+def comment_out_env_key(text: str, key: str) -> str:
+    """Turn ``KEY=...`` into a bare ``# KEY=`` placeholder, in place if present."""
+    lines = text.splitlines()
+    placeholder = f"# {key}="
+    hits = [i for i, ln in enumerate(lines) if ln.startswith((f"{key}=", placeholder))]
+    if hits:
+        lines[hits[0]] = placeholder
+        lines = [ln for i, ln in enumerate(lines) if i not in hits[1:]]
+    else:
+        if _SECRET_NOTE.splitlines()[0] not in lines:
+            lines += ["", *_SECRET_NOTE.splitlines()]
+        lines.append(placeholder)
+    return "\n".join(lines) + "\n"
+
+
+def add_postgres_password_placeholder(text: str) -> str:
+    """Add an empty ``POSTGRES_PASSWORD=`` to ``.env.example``, with its URL-safe note."""
+    text = set_env_key(text, "POSTGRES_PASSWORD", "")
+    return text.replace("POSTGRES_PASSWORD=\n", _PG_PASSWORD_NOTE + "POSTGRES_PASSWORD=\n", 1)
+
+
+def write_local_env(
+    target: Path, *, secret_keys: Iterable[str], overrides: dict[str, str] | None = None
+) -> None:
+    """Write ``target/.env`` from ``.env.example`` plus generated secrets.
+
+    ``secret_keys`` get a fresh random value each; ``overrides`` are written
+    verbatim (e.g. a database URL carrying a generated password). Overrides
+    belong together, so an existing ``.env`` defining any of them gets none:
+    a fresh URL must not disagree with a kept ``POSTGRES_PASSWORD``.
+    """
+    env_path = target / ".env"
+    existing = env_path.exists()
+    source = env_path if existing else target / ".env.example"
+    text = source.read_text(encoding="utf-8") if source.exists() else ""
+    defined = env_values(text).keys()
+    overrides = overrides or {}
+    if existing and defined & overrides.keys():
+        overrides = {}
+    values = {key: secrets.token_urlsafe(32) for key in secret_keys} | overrides
+    for key, value in values.items():
+        if existing and key in defined:
+            continue
+        placeholder = f"# {key}="
+        lines = text.splitlines()
+        if placeholder in lines:
+            # Line-based, so a placeholder on the last line (no trailing
+            # newline) is handled too.
+            lines[lines.index(placeholder)] = f"{key}={value}"
+            text = "\n".join(lines) + "\n"
+        else:
+            text = set_env_key(text, key, value)
+    env_path.write_text(text, encoding="utf-8")
+    env_path.chmod(0o600)  # holds generated secrets

{simple_module_cli-0.0.35 → simple_module_cli-0.0.37}/simple_module_cli/add_cmd.py

@@ -11,6 +11,7 @@ sync-js-deps`` → entry-point verification, unless ``--no-sync``.
 
 from __future__ import annotations
 
+import os
 import subprocess
 import tempfile
 from collections.abc import Callable
@@ -35,7 +36,9 @@ from simple_module_cli.pyproject_edit import (
     write_dependency,
     write_git_source,
     write_path_source,
+    write_workspace_source,
 )
+from simple_module_cli.uv_workspace import is_workspace_member
 
 __all__ = ["ExecRunner", "add_module", "post_install", "run_add"]
 
@@ -137,18 +140,46 @@ def _add_pypi(doc, pyproject: Path, raw: str, no_sync: bool, exec_runner: ExecRu
     return [name]
 
 
+def _resolve_local_path(project_dir: Path, spec_path: Path) -> tuple[Path, str]:
+    """Resolve a local-path spec to ``(directory, text written to pyproject)``.
+
+    A relative path is resolved against the ``--path`` project (the pyproject
+    being edited, which is what ``[tool.uv.sources]`` paths are relative to).
+    If nothing exists there but the path exists relative to the cwd, the cwd
+    one is used and the written path is re-expressed relative to the project.
+    """
+    if spec_path.is_absolute():
+        return spec_path, str(spec_path)
+    root = project_dir / spec_path
+    if not root.exists() and (Path.cwd() / spec_path).exists():
+        root = Path.cwd() / spec_path
+        return root, os.path.relpath(root.resolve(), project_dir.resolve())
+    return root, str(spec_path)
+
+
 def _add_path(
     doc, pyproject: Path, spec_path: Path, no_sync: bool, exec_runner: ExecRunner
 ) -> list[str]:
-    root = spec_path if spec_path.is_absolute() else pyproject.parent / spec_path
+    root, written = _resolve_local_path(pyproject.parent, spec_path)
     found = [m for m in scan_modules(root) if m.subdirectory is None]
     if not found:
-        raise _fail(f"{root} has no [project.entry-points.simple_module] entry point at its root")
+        raise _fail(
+            f"{root} has no [project.entry-points.simple_module] entry point at its root "
+            f"(relative paths resolve against the --path project, {pyproject.parent}, "
+            "falling back to the current directory)"
+        )
     mod = found[0]
-    write_dependency(doc, mod.dist_name, derive_range(mod.version))
-    write_path_source(doc, mod.dist_name, path=str(spec_path))
+    if is_workspace_member(pyproject.parent, root):
+        # uv refuses a path source for a workspace member; the scaffold's own
+        # sample module is wired the same way (unpinned + workspace = true).
+        write_dependency(doc, mod.dist_name, "")
+        write_workspace_source(doc, mod.dist_name)
+        typer.echo(f"Added {mod.dist_name} (uv workspace member {written}).")
+    else:
+        write_dependency(doc, mod.dist_name, derive_range(mod.version))
+        write_path_source(doc, mod.dist_name, path=written)
+        typer.echo(f"Added {mod.dist_name} (editable path {written}).")
     save_pyproject(pyproject, doc)
-    typer.echo(f"Added {mod.dist_name} (editable path {spec_path}).")
     if not no_sync:
         post_install(
             pyproject.parent,

{simple_module_cli-0.0.35 → simple_module_cli-0.0.37}/simple_module_cli/app_project.py

@@ -20,7 +20,12 @@ from pathlib import Path
 from typing import Any
 
 from simple_module_cli._env import set_env_key
-from simple_module_cli.case import to_kebab_case, to_pascal_case
+from simple_module_cli._local_env import (
+    add_postgres_password_placeholder,
+    comment_out_env_key,
+    write_local_env,
+)
+from simple_module_cli.case import to_kebab_case, to_pascal_case, to_snake_case
 from simple_module_cli.catalog import CATALOG, PRESETS, expand_deps
 from simple_module_cli.docker_assets import scaffold_docker_assets
 from simple_module_cli.recipes import RECIPES, ScaffoldCtx
@@ -52,6 +57,8 @@ _APP_PY_DEV_DEPS = [
     "pytest>=8.0",
     "pytest-asyncio>=0.24",
     "pytest-playwright>=0.7.2",
+    # Floor: unpinned, uv backtracks playwright to 1.18 (GH #445).
+    "playwright>=1.45",
     "ruff>=0.8",
     "ty>=0.0.29",
 ]
@@ -150,19 +157,33 @@ def create_app_project(
         py_deps.append(_SAMPLE_MODULE_PKG)
         workspace_sources.append(_SAMPLE_MODULE_PKG)
 
-    env_path = target / ".env.example"
-    env_text = env_path.read_text(encoding="utf-8") if env_path.exists() else ""
-    env_text = set_env_key(env_text, "SM_SECRET_KEY", _secrets.token_urlsafe(32))
+    # Generated secrets go to the gitignored .env, never the committed
+    # .env.example (GH #441) — see write_local_env below.
+    secret_keys = ["SM_SECRET_KEY"]
     if "users" in resolved:
         # UsersSettings refuses its placeholder token secrets when
         # SM_ENVIRONMENT=production — the mode the compose containers run
-        # in — so generate real ones, same as SM_SECRET_KEY above.
-        for key in (
+        # in — so generate real ones, same as SM_SECRET_KEY.
+        secret_keys += [
             "SM_USERS_RESET_PASSWORD_TOKEN_SECRET",
             "SM_USERS_VERIFICATION_TOKEN_SECRET",
-        ):
-            env_text = set_env_key(env_text, key, _secrets.token_urlsafe(32))
-    env_text = set_env_key(env_text, "SM_DATABASE_URL", _db_url(db, to_kebab_case(name), flat=flat))
+        ]
+    db_name = to_snake_case(name)
+    env_path = target / ".env.example"
+    env_text = env_path.read_text(encoding="utf-8") if env_path.exists() else ""
+    for key in secret_keys:
+        env_text = comment_out_env_key(env_text, key)
+    local_overrides: dict[str, str] = {}
+    if db == "postgres":
+        # The compose `postgres` service takes its password from .env, and
+        # the dev SM_DATABASE_URL must match it (GH #444).
+        env_text = add_postgres_password_placeholder(env_text)
+        password = _secrets.token_urlsafe(24)
+        local_overrides = {
+            "POSTGRES_PASSWORD": password,
+            "SM_DATABASE_URL": _db_url(db, db_name, flat=flat, password=password),
+        }
+    env_text = set_env_key(env_text, "SM_DATABASE_URL", _db_url(db, db_name, flat=flat))
     env_text = set_env_key(env_text, "SM_MULTI_TENANT", "true" if tenancy else "false")
     env_path.write_text(env_text, encoding="utf-8")
 
@@ -198,6 +219,8 @@ def create_app_project(
             RECIPES[recipe_key].apply(target, ctx)
 
     scaffold_docker_assets(target, ctx, flat=flat)
+    # Last, so .env picks up every key the recipes added to .env.example.
+    write_local_env(target, secret_keys=secret_keys, overrides=local_overrides)
 
     return host_dir, preserved
 
@@ -234,9 +257,9 @@ def _seed_static_dist_placeholder(static_dist: Path) -> None:
     (static_dist / ".gitkeep").touch()
 
 
-def _db_url(db: str, slug: str, *, flat: bool) -> str:
+def _db_url(db: str, db_name: str, *, flat: bool, password: str = "<POSTGRES_PASSWORD>") -> str:
     if db == "postgres":
-        return f"postgresql+asyncpg://postgres:postgres@localhost:5432/{slug}"
+        return f"postgresql+asyncpg://postgres:{password}@localhost:5432/{db_name}"
     # Workspace mode keeps the SQLite file next to host/'s alembic.ini so
     # `cd host && uvicorn` and `cd host && alembic` resolve the same path.
     return "sqlite+aiosqlite:///./app.db" if flat else "sqlite+aiosqlite:///./host/app.db"

{simple_module_cli-0.0.35 → simple_module_cli-0.0.37}/simple_module_cli/cli.py

@@ -14,6 +14,7 @@ group are mounted as named subgroups (e.g. ``smpy host gen-pages``).
 
 from __future__ import annotations
 
+import os
 from pathlib import Path
 from typing import Annotated
 
@@ -23,6 +24,7 @@ from simple_module_cli.add_cmd import add_module, run_add
 from simple_module_cli.case import to_kebab_case
 from simple_module_cli.module_cmd import module_app
 from simple_module_cli.new import new_project
+from simple_module_cli.openapi_cmd import openapi_app
 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
@@ -30,6 +32,7 @@ from simple_module_cli.scaffolding import create_module as _create_module
 from simple_module_cli.scaffolding import is_inside_existing_repo, resolve_framework_version
 from simple_module_cli.skills_cmd import app as skills_app
 from simple_module_cli.update_cmd import update_modules
+from simple_module_cli.uv_workspace import find_workspace_root, is_workspace_member
 
 app = typer.Typer(
     help="SimpleModule developer CLI.",
@@ -43,6 +46,7 @@ app.command("update")(update_modules)
 app.command("package-update")(package_update)
 app.add_typer(skills_app, name="skills")
 app.add_typer(module_app, name="module")
+app.add_typer(openapi_app, name="openapi")
 
 
 @app.command("create-host")
@@ -103,6 +107,27 @@ def create_host(
     typer.echo("  python main.py")
 
 
+def _echo_workspace_hint(target: Path) -> None:
+    """Tell the user how to wire a workspace-member module into the host (GH #442)."""
+    root = find_workspace_root(target.parent)
+    if root is None:
+        return
+    host = root / "host"
+    if not (host / "pyproject.toml").is_file() or not is_workspace_member(host, target):
+        return
+    rel = os.path.relpath(target.resolve(), host.resolve())
+    if not rel.startswith("."):
+        rel = f"./{rel}"  # parse_add_spec reads a bare "a/b" as a PyPI requirement
+    host_arg = os.path.relpath(host.resolve(), Path.cwd())
+    if host_arg.startswith(".."):
+        host_arg = str(host.resolve())
+    typer.echo(
+        f"\nThis module is a uv workspace member. Wire it into the host with:\n"
+        f"  smpy add {rel} --path {host_arg}"
+        "   # adds it as { workspace = true }"
+    )
+
+
 @app.command("create-module")
 def create_module(
     name: Annotated[str, typer.Argument(help="Module name (any case).")],
@@ -149,6 +174,7 @@ def create_module(
             "Skipped .github/ workflows: this module is inside an existing repo, "
             "where nested workflows never run. Use --standalone to emit them."
         )
+    _echo_workspace_hint(target)
     typer.echo("\nNext steps:")
     typer.echo(f"  cd {target}")
     typer.echo("  uv sync --extra dev")

{simple_module_cli-0.0.35 → simple_module_cli-0.0.37}/simple_module_cli/docker_assets.py

@@ -19,7 +19,7 @@ import importlib.resources
 import shutil
 from pathlib import Path
 
-from simple_module_cli.case import to_kebab_case
+from simple_module_cli.case import to_snake_case
 from simple_module_cli.recipes import ScaffoldCtx
 
 __all__ = ["scaffold_docker_assets"]
@@ -70,7 +70,8 @@ def scaffold_docker_assets(target: Path, ctx: ScaffoldCtx, *, flat: bool = False
     # compiles to DEFAULT 0 on SQLite, which Postgres rejects), so pointing
     # a sqlite-scaffolded app at a Postgres container fails on first boot.
     db = "postgres" if ctx.db == "postgres" else "sqlite"
-    pg_db = to_kebab_case(ctx.name)
+    # snake_case: a kebab name needs quoting in every psql call (GH #443).
+    pg_db = to_snake_case(ctx.name)
     with_tasks = "background_tasks" in ctx.selected
     compose = (
         _read(templates / f"compose-base-{db}.yml.tpl")

{simple_module_cli-0.0.35 → simple_module_cli-0.0.37}/simple_module_cli/new.py

@@ -170,6 +170,7 @@ def new_project(
         for path in preserved:
             rel = path.relative_to(target) if path.is_relative_to(target) else path
             typer.echo(f"  {rel}")
+    typer.echo("\nGenerated secrets were written to .env (gitignored), not .env.example.")
     typer.echo("\nNext steps:")
     typer.echo(f"  cd {target}")
     if no_install:

simple_module_cli-0.0.37/simple_module_cli/openapi_cmd.py

@@ -0,0 +1,81 @@
+"""``smpy openapi`` — export the host's OpenAPI document without a server (#456).
+
+The app is built in process with ``create_app`` and its schema is written to a
+file, so CI can generate API clients from a checkout. ``simple_module_hosting``
+is imported inside the command: the CLI package depends only on typer and
+tomlkit (``test_no_framework_deps``), and the hosting stack exists only in a
+host's environment (run via ``uv run smpy openapi export``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+openapi_app = typer.Typer(help="OpenAPI schema tools.", no_args_is_help=True)
+
+
+def _norm(name: str) -> str:
+    """``feature_flags`` and the ``FeatureFlags`` tag compare equal."""
+    return name.replace("_", "").replace("-", "").lower()
+
+
+def _filter_modules(schema: dict, modules: list[str]) -> dict:
+    """Keep operations whose first tag is one of ``modules`` (case and underscores ignored)."""
+    wanted = {_norm(m) for m in modules}
+    paths: dict = {}
+    for path, item in schema.get("paths", {}).items():
+        kept = {
+            method: op
+            for method, op in item.items()
+            if isinstance(op, dict) and _norm((op.get("tags") or [""])[0]) in wanted
+        }
+        if kept:
+            paths[path] = kept
+    return {**schema, "paths": paths}
+
+
+@openapi_app.command("export")
+def export(
+    out: Annotated[Path, typer.Option("--out", help="File to write.")] = Path("openapi.json"),
+    module: Annotated[
+        list[str] | None,
+        typer.Option("--module", help="Only include this module's operations. Repeatable."),
+    ] = None,
+) -> None:
+    """Write the host's OpenAPI document (``/api/**`` only) to ``--out``."""
+    project_root = Path(os.environ.get("SM_PROJECT_ROOT") or Path.cwd())
+    os.environ.setdefault("SM_PROJECT_ROOT", str(project_root))
+
+    try:
+        from simple_module_core.dotenv import load_dotenv_into_environ
+        from simple_module_hosting import create_app, merge_host_settings
+        from simple_module_hosting._preapp_config import load_host_overrides
+        from simple_module_hosting.bootstrap_settings import BootstrapSettings
+    except ImportError:
+        typer.echo(
+            "error: simple_module_hosting is not installed — run this from a host "
+            "project (`uv run smpy openapi export`).",
+            err=True,
+        )
+        raise typer.Exit(code=1) from None
+
+    load_dotenv_into_environ(project_root / ".env")
+    if not load_host_overrides(BootstrapSettings().database_url):
+        typer.echo(
+            "warning: no host settings found in the database (unreachable, not migrated or "
+            "empty); using environment and defaults for api_title / api_version.",
+            err=True,
+        )
+    settings = merge_host_settings()
+    schema = create_app(settings).openapi()
+    if module:
+        schema = _filter_modules(schema, module)
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(schema, indent=2, sort_keys=False) + "\n", encoding="utf-8")
+    typer.echo(f"wrote {out} ({len(schema.get('paths', {}))} paths)")

{simple_module_cli-0.0.35 → simple_module_cli-0.0.37}/simple_module_cli/pyproject_edit.py

@@ -24,6 +24,7 @@ __all__ = [
     "write_dependency",
     "write_git_source",
     "write_path_source",
+    "write_workspace_source",
 ]
 
 
@@ -90,6 +91,15 @@ def _uv_sources(doc: tomlkit.TOMLDocument) -> Table:
     return uv.setdefault("sources", tomlkit.table())
 
 
+def _set_source(doc: tomlkit.TOMLDocument, dist_name: str, src: Any) -> bool:
+    """Write ``src`` under ``[tool.uv.sources]``; False when already identical."""
+    sources = _uv_sources(doc)
+    if dist_name in sources and dict(sources[dist_name]) == dict(src):
+        return False
+    sources[dist_name] = src
+    return True
+
+
 def write_git_source(
     doc: tomlkit.TOMLDocument,
     dist_name: str,
@@ -104,22 +114,21 @@ def write_git_source(
         src[ref_info.kind] = ref_info.value
     if subdirectory:
         src["subdirectory"] = subdirectory
-    sources = _uv_sources(doc)
-    if dist_name in sources and dict(sources[dist_name]) == dict(src):
-        return False
-    sources[dist_name] = src
-    return True
+    return _set_source(doc, dist_name, src)
 
 
 def write_path_source(doc: tomlkit.TOMLDocument, dist_name: str, *, path: str) -> bool:
     src = tomlkit.inline_table()
     src["path"] = path
     src["editable"] = True
-    sources = _uv_sources(doc)
-    if dist_name in sources and dict(sources[dist_name]) == dict(src):
-        return False
-    sources[dist_name] = src
-    return True
+    return _set_source(doc, dist_name, src)
+
+
+def write_workspace_source(doc: tomlkit.TOMLDocument, dist_name: str) -> bool:
+    """``dist = { workspace = true }`` — required for uv workspace members."""
+    src = tomlkit.inline_table()
+    src["workspace"] = True
+    return _set_source(doc, dist_name, src)
 
 
 def _sources_dict(doc: tomlkit.TOMLDocument) -> dict[str, Any]:

{simple_module_cli-0.0.35 → simple_module_cli-0.0.37}/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–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".
+description: Use when interpreting a simple_module_python diagnostic code (SM001–SM029) 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
@@ -33,6 +33,8 @@ You can also call `run_diagnostics(...)` from `simple_module_core` programmatica
 | **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`) |
+| **SM028** | WARNING | A module's `tasks.py` imports `torch`, `tensorflow`, `ultralytics`, `osgeo`, `rasterio`, `cv2` or `sklearn` at module level | Import the package inside the task function, so only a worker that runs the task loads it |
+| **SM029** | INFO | A module overrides `db_extensions()` (Postgres extensions like `ltree`) but the database is SQLite, which has none; `ensure_db_extensions` raises `UnsupportedDatabaseError` at migrate time | Point `SM_DATABASE_URL` at PostgreSQL |
 
 `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`.
 

{simple_module_cli-0.0.35 → simple_module_cli-0.0.37}/simple_module_cli/skills/simple-module-migrations/SKILL.md

@@ -64,7 +64,7 @@ make migration msg="add orders module"
 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.
+`make migrate` runs `alembic -c host/alembic.ini upgrade heads` — note **`heads`** (plural). Histories with a branch label can end up with multiple heads, so `upgrade head` (singular) may error or under-apply.
 
 ### Branch labels — set on the FIRST revision per module
 
@@ -78,16 +78,14 @@ 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, which is how a module is uninstalled cleanly:
+Why: the label is a named target for that revision (`upgrade audit_log@head`, the module column in the Doctor). It does **not** isolate the module: autogenerate chains the revision off the current head, so history is one linear chain and `downgrade audit_log@base` walks the **entire chain beneath it, other modules included**. Never use it as a per-module rollback.
 
-```bash
-make downgrade   # back one revision; OR, to a target:
-uv run --project host alembic -c host/alembic.ini downgrade audit_log@base
-```
+To remove one module's schema:
 
-`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.
+- If the module's revisions are the latest in the chain, downgrade to the `down_revision` of its first revision: `uv run --project host alembic -c host/alembic.ini downgrade <that down_revision id>`.
+- Otherwise write a dedicated migration that drops that module's tables.
 
-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; they chain off it as ordinary revisions.
 
 > 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.
 
@@ -112,7 +110,7 @@ SM010/SM011 are **not** emitted at boot or by `make doctor`. They only surface w
 
 ## Pitfalls
 
-- **Skipped the branch label on the first revision.** `alembic downgrade <module>@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.
+- **Treating `downgrade <module>@base` as a per-module rollback.** It rolls back every revision beneath the labelled one, other modules included. See the recipe under "Branch labels".
 - **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 `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.

simple_module_cli-0.0.37/simple_module_cli/templates/docker/Makefile.snippet

@@ -0,0 +1,25 @@
+# --- docker --------------------------------------------------------------
+.PHONY: docker-build docker-up docker-down
+
+docker-build:               ## Build the app image
+	docker compose build
+
+docker-up:                  ## Run the full stack in containers
+	@test -f .env || { cp .env.example .env; \
+		echo "Created .env from .env.example: set POSTGRES_PASSWORD (Postgres apps) and the"; \
+		echo "commented SM_* secrets in .env; production containers refuse to boot without them."; }
+	@# compose interpolates POSTGRES_PASSWORD raw into the SM_DATABASE_URL, so it must be URL-safe.
+	@# The value is read the way compose reads it: last definition wins, CRLF, an inline
+	@# trailing comment and surrounding quotes are not part of the password.
+	@pw=$$(sed -n 's/^POSTGRES_PASSWORD=//p' .env | tail -n 1 | tr -d '\r' \
+		| sed -e 's/[[:space:]]#.*$$//' -e 's/[[:space:]]*$$//' -e 's/^"\(.*\)"$$/\1/' -e "s/^'\(.*\)'$$/\1/"); \
+	if printf '%s' "$$pw" | grep -q '[^A-Za-z0-9._~-]'; then \
+		echo "POSTGRES_PASSWORD in .env must be URL-safe (letters, digits, - _ . ~ only):" >&2; \
+		echo "compose puts it into SM_DATABASE_URL unencoded. Pick another password." >&2; \
+		exit 1; \
+	fi
+	docker compose up --build
+
+docker-down:                ## Stop the compose stack
+	docker compose down
+# --- end docker ----------------------------------------------------------

{simple_module_cli-0.0.35 → simple_module_cli-0.0.37}/simple_module_cli/templates/docker/compose-base-postgres.yml.tpl

@@ -4,9 +4,11 @@ services:
     environment:
       POSTGRES_DB: "{{PG_DB}}"
       POSTGRES_USER: postgres
-      POSTGRES_PASSWORD: postgres
+      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}"
     ports:
-      - "5432:5432"
+      # Loopback only: reachable as a local dev database, never from the
+      # network. The app reaches it over the compose network (GH #444).
+      - "127.0.0.1:5432:5432"
     volumes:
       - pgdata:/var/lib/postgresql/data
     healthcheck:
@@ -26,7 +28,7 @@ services:
       # Containers serve the built bundle; development mode would emit
       # asset tags pointing at the (absent) Vite dev server.
       SM_ENVIRONMENT: production
-      SM_DATABASE_URL: postgresql+asyncpg://postgres:postgres@postgres:5432/{{PG_DB}}
+      SM_DATABASE_URL: "postgresql+asyncpg://postgres:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}@postgres:5432/{{PG_DB}}"
 {{APP_EXTRA_ENV}}    ports:
       - "8000:8000"
     depends_on: