Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,14 @@ All notable changes to this project are documented in this file. The format is b

## [Unreleased]

### Fixed

- `smpy new` apps keep `simple_module_cli` in the workspace root's `dev` group, so a plain `uv sync` no longer uninstalls it and `uv run smpy` no longer falls through to an older global `smpy`. Inside a project, `smpy` now warns when the project pins the framework to another version than its own (except `new`, `update` and `package-update`), and `smpy doctor` run by a CLI outside the project's venv says so instead of "run it inside a project". Existing apps: add `"simple_module_cli==<version>"` to `[dependency-groups] dev` in the root `pyproject.toml` (#929).
- `make dev` reloads when a `locales/*.json` catalog changes: the app template's `dev-api` (and this repository's) pass `--reload-include '*locales/*.json'`, since uvicorn watches only `*.py`. Existing apps: add that flag to the `uvicorn` line of `dev-api` (#930).
- `smpy add` ends with "If `make dev` is running, restart it" (the module 404s until a restart), and suggests `make migration msg="add <name>"` like `create-module`. `create-module`'s next steps and the landing page say `uv run smpy` (#931).
- `smpy new` retries its `uv sync` once with `--refresh` when it fails, so a uv index cache from before a release no longer breaks the first app made with it; if the retry fails too, the next steps say it was already retried and to wait for PyPI before `make install` (#932).
- **Behaviour change:** `make_process_revision_directives` ignores SQLAlchemy's and Alembic's SQLite warnings about the expression indexes the models declare (the hook re-emits them for new tables and names any the database lacks), and SM026 plus the boot-time note now report only expression indexes the SQLite database does not have by name. A migrated fresh app prints neither (#933).

## [0.0.46] — 2026-11-13

### Changed
Expand Down
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ dev: docker-up gen-pages
$(MAKE) -j2 dev-api dev-ui

dev-api:
uv run --project host uvicorn host.main:app --reload --port 8000
uv run --project host uvicorn host.main:app --reload --reload-include '*locales/*.json' --port 8000

dev-ui:
npm run dev
Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ make migration msg="add orders tables" # review the generated revision
make migrate
```

That generates `modules/orders/` with a `ModuleMeta`, a SQLModel table, contracts, a service, REST + Inertia endpoints, three React pages, locales, and a smoke test, wires it into the host and creates its table; the dev server picks it up when it reloads. The full walkthrough is in [Your first module](/guide/first-module).
That generates `modules/orders/` with a `ModuleMeta`, a SQLModel table, contracts, a service, REST + Inertia endpoints, three React pages, locales, and a smoke test, wires it into the host and creates its table; restart `make dev` to serve it, since modules are discovered at start-up. The full walkthrough is in [Your first module](/guide/first-module).

## Where to start

Expand Down
5 changes: 3 additions & 2 deletions docs/module-authoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,8 +366,9 @@ generated file against this checklist before treating it as portable
re-emits the expression indexes of every table a revision creates, so an
initial schema needs nothing. When the models declare an expression index the
database does not have (one added to an existing table), autogenerate on
SQLite logs a banner naming it, and `make doctor` reports `SM026` for every
expression index. Add it to the revision by hand
SQLite logs a banner naming it, and `make doctor` reports it as `SM026`
(SQLAlchemy's and Alembic's own warnings about declared expression indexes
are silenced, since the hook covers them). Add it to the revision by hand
(`op.create_index(..., [sa.text("lower(email)")], if_not_exists=True)`) and
confirm with the PostgreSQL round trip below; in an app without that make
target, point `SM_DATABASE_URL` at a PostgreSQL database, run `make migrate`,
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/diagnostic-codes.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ The framework runs a set of static checks over installed modules at app boot. Th
| `SM023` | WARNING | A module's `theme.css` contains an unlayered plain rule (anything but an at-rule or a `:root`-style selector). Unlayered CSS outranks every Tailwind utility. | Move the rule to the module's `styles.css`, which is imported into `layer(components)` so utilities still win. |
| `SM024` | WARNING | A unique column, constraint or index on a `MultiTenantMixin` table does not include `tenant_id`, so the first tenant to claim a value locks every other tenant out of it. | Make the key per tenant: add `tenant_id` to it (`Index(..., "tenant_id", "slug", unique=True)`). |
| `SM025` | WARNING | `multi_tenant` is on but no module registered `app.state.tenant_resolver`, so only the principal's `tenant_id` claim can bind a tenant — with most auth providers every tenant-scoped query then fails closed. Checked at boot (it needs the built app), in every environment, not by `make doctor`. | Install the `tenants` module, or register your own `async (Request) -> str \| None` resolver on `app.state.tenant_resolver`. |
| `SM026` | INFO | The configured database is SQLite and a module model declares an expression index (e.g. `lower(email)`). SQLite cannot reflect those, so autogenerate and `alembic check` cannot verify them and a clean diff says nothing about them. | Add the index to a revision by hand and verify on PostgreSQL: `make migrations-roundtrip-pg` in this repository, `make migrate` then `alembic check` against a PostgreSQL `SM_DATABASE_URL` in an app. See [Migrations](/module-authoring#reviewing-a-revision-autogenerated-on-sqlite). |
| `SM026` | INFO | The configured database is SQLite and a module model declares an expression index (e.g. `lower(email)`) that the database does not have by name (every one when the database file cannot be read). SQLite cannot reflect those, so autogenerate and `alembic check` cannot verify them and a clean diff says nothing about them. | Add the index to a revision by hand and verify on PostgreSQL: `make migrations-roundtrip-pg` in this repository, `make migrate` then `alembic check` against a PostgreSQL `SM_DATABASE_URL` in an app. See [Migrations](/module-authoring#reviewing-a-revision-autogenerated-on-sqlite). |
| `SM027` | WARNING | A key in `host/locales/overrides/<locale>.json` matches no catalog key, so the override was skipped. Reported by `make doctor` and at dev boot. | Fix the key: overrides replace an existing key by its full dotted path (e.g. `users.login.aside_heading`). See [i18n](/framework/i18n#overriding-module-copy). |
| `SM028` | WARNING | A module's `tasks.py` imports `torch`, `tensorflow`, `ultralytics`, `osgeo`, `rasterio`, `cv2` or `sklearn` at module level, so every process that loads the module's tasks (web, each worker, beat) pays for it and a queue-restricted worker cannot avoid it. | Import the package inside the task function. See [background_tasks](/modules/background_tasks#running-a-worker-for-a-subset-of-modules). |
| `SM029` | INFO | A module overrides `db_extensions()` (Postgres extensions such as `ltree`) and the configured database is SQLite, which has none. `ensure_db_extensions` raises `UnsupportedDatabaseError` when migrations run. | Point `SM_DATABASE_URL` at PostgreSQL. See [Postgres extensions and column types](/database/extensions). |
Expand Down
19 changes: 19 additions & 0 deletions docs/superpowers/plans/2026-11-13-issues-929-933.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Issues #929–#933 implementation plan

Design: `docs/superpowers/specs/2026-11-13-issues-929-933-design.md`. All tasks
touch disjoint files except the CHANGELOG (last task). Each: test first, then fix,
then `uv run pytest framework/cli` (or the package touched), then commit.

1. **#929 CLI pin + doctor message + mismatch notice.** `templates/workspace/pyproject.toml.tpl`,
`cli.py` (doctor), new `_project_cli_check.py` (callback warning). Tests in
`framework/cli/tests/`. Done: render test sees the pin; doctor/mismatch tests pass.
2. **#930 locale reload.** App template `Makefile`, root `Makefile`. Test: template
Makefile contains `--reload-include '*locales/*.json'`.
3. **#931 hints.** `_add_install.py` (restart line, short migration name), `cli.py`
`_echo_app_next_steps`. Tests on the echoed text.
4. **#932 refresh retry.** `new.py` install phase. Test with a fake `subprocess.run`.
5. **#933 warnings + SM026 (hard).** `simple_module_db/migrations.py` /
`migration_portability.py` (filters), `migration_state.py` (index names),
`_migration_doctor.py` / `__main__.py` / `_expression_index.py` (SM026 filter),
`simple_module_hosting/migrations.py` (boot log filter). Tests in db/core.
6. CHANGELOG `[Unreleased]`, docs touched by behaviour (diagnostic-codes SM026), full lint + tests.
103 changes: 103 additions & 0 deletions docs/superpowers/specs/2026-11-13-issues-929-933-design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
# Issues #929–#933: fresh-app DX follow-ups to 0.0.46

Five bugs found on a fresh 0.0.46 app (`smpy new` → `create-module` → `smpy add`
→ `make dev`). One branch, one PR, one commit per issue.

## Goal & scope

In: the five issues below. Out: #580 (SSR, deferred), and any change to how
modules are discovered at runtime (a restart stays necessary after `smpy add`).

## #929 — plain `uv sync` uninstalls `simple_module_cli`

- Add `simple_module_cli=={{FRAMEWORK_VERSION}}` to the workspace root
`[dependency-groups] dev` in `templates/workspace/pyproject.toml.tpl`, next to
`simple_module_test`. `smpy package-update` already rewrites `simple_module_*`
pins in every dependency group, so updates keep it in step.
- `smpy doctor` without `simple_module_core`: when the cwd is inside an app
(`find_workspace_root` finds a project), say the `smpy` that ran is not the
project's (print its version and path) and give the fix (`uv sync --all-packages`,
then `uv run smpy …`), instead of "run it inside a project".
- Version-mismatch notice: every `smpy` invocation inside an app whose
pyproject pins `simple_module_cli==X` (or, failing that, `simple_module_core==X`)
with `X` ≠ the running CLI's version prints one stderr warning naming both
versions and the executable path. Warning only, never blocks.

## #930 — editing `locales/*.json` doesn't reload under `make dev`

- App template `Makefile` `dev-api`: add `--reload-include '*locales/*.json'`
(matches module `locales/` and the host's; `Path.match` is right-anchored, so
`package.json` and the rest are not watched). A reload re-runs the dev boot,
which regenerates i18n keys.
- Framework repo's own `make dev`: same flag, for parity.
- Fix the Makefile comment that claimed locales already reloaded.
- Existing apps: CHANGELOG entry gives the one-line Makefile edit.

## #931 — no restart hint after `smpy add`

- `smpy add` (after a successful sync): print "If `make dev` is running,
restart it: modules are discovered at start-up, not on reload." Always, not
port-probed: a probe adds a failure mode and a stale-port false negative for
one line of text.
- `create-module` next steps: `uv run smpy add …` (not bare `smpy`); migration
message uses the same slug as `smpy add`'s hint; drop `make install` if `smpy add`
already covers it (it runs `uv sync --all-packages`, gen-pages and sync-js-deps;
if the new npm workspace member still needs `npm install`, print that instead).
- `smpy add`'s migration hint uses the short module name (`add bookmarks`,
`simple_module_` prefix stripped) to match.

## #932 — `smpy new` hits uv's stale index right after a release

- In `smpy new`'s install phase, when `uv sync` fails, retry once with
`--refresh`, printing "uv's cached PyPI index may predate this release;
retrying with --refresh". Only the second failure prints the uv output and the
manual-setup warning.
- Rejected: always passing `--refresh-package` for every pinned package — ~20
extra index fetches on every `smpy new`, for a failure that only happens in the
minutes after a release.
- When the retry also fails (or install is skipped), next steps say
`uv sync --all-packages --refresh` helps if resolution fails on a just-released
version.

## #933 — library warnings on every `make migration`, SM026 on every doctor

- `make_process_revision_directives(metadata)` (already called by every app's
`env.py`, so existing apps get it without a template change) installs
`warnings.filterwarnings("ignore", …)` for the SQLAlchemy `SAWarning`
("Skipped unsupported reflection of expression-based index …") and Alembic's
`UserWarning` ("autogenerate skipping metadata-specified expression-based index
…"), narrowed to the expression-index names the metadata declares. The hook
already re-emits these for new tables and names the ones the database lacks.
- SM026: report only expression indexes whose name the SQLite database does
not have. Doctor already reads the database for SM010/SM011; extend that read
(`read_migration_state`) with SQLite index names and pass them to SM026. No
database reachable → unchanged behaviour (report all). A fresh migrated app
then shows no SM026. The dev-boot path keeps reporting through the existing
`_note_unverifiable_expression_indexes` log, filtered the same way.

## Decisions made (override any)

- One PR for all five (they share the CLI and template; previous batches did the same).
- Version-mismatch notice is a warning, not an error.
- `smpy add` restart hint is unconditional.
- `--refresh` on retry, not up front.
- Warning filters live in `simple_module_db`, not the template `env.py`, so existing apps benefit.

## Testing

- Unit: template render contains the cli pin; doctor error text inside/outside an
app; mismatch notice (pinned ≠ running, equal, no app); `smpy new` retry path
with a fake runner (fail → refresh → ok; fail twice); `smpy add` output; create-module
next steps; warning filter (emits nothing for declared names, still warns for
undeclared); SM026 with and without existing index names.
- Integration: existing scaffold tests (`smpy new` e2e with local sources) still pass.
- Manual: scaffold an app from the branch, `uv sync`, `uv run which smpy`,
`make migration` output, `smpy doctor`, edit `locales/en.json` under `make dev`
and see a reload.

## Risks

- Alembic/SQLAlchemy warning text could change; the filter then stops
matching and the warnings come back (harmless). Tests pin the current text.
- `npm install` may still be needed after `smpy add` for a new npm workspace
member; verified during implementation before dropping `make install`.
11 changes: 10 additions & 1 deletion framework/cli/simple_module_cli/_add_install.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

from __future__ import annotations

import re
import subprocess
from collections.abc import Callable
from pathlib import Path
Expand All @@ -12,6 +13,8 @@

ExecRunner = Callable[[list[str], Path], int]

_DIST_PREFIX = re.compile(r"^simple[-_]module[-_]", re.IGNORECASE)


_ENTRYPOINT_CHECK = (
"import sys\n"
Expand Down Expand Up @@ -77,7 +80,13 @@ def post_install(
"entry point — it is not a SimpleModule module."
)
for dist in models_dists:
# The same message `smpy create-module`'s next steps suggest (GH #931).
slug = _DIST_PREFIX.sub("", dist)
typer.echo(
f"{dist} ships database models — generate and apply the migration:\n"
f' make migration msg="add {dist}"\n make migrate'
f' make migration msg="add {slug}"\n make migrate'
)
# Only `pyproject.toml` changed, which the dev reloader does not watch; and a
# reload still logs the new module as not importable in that process (GH #915,
# #931), so only a restart serves it.
typer.echo("If `make dev` is running, restart it: modules are discovered at start-up.")
84 changes: 84 additions & 0 deletions framework/cli/simple_module_cli/_project_cli_check.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
"""Notice when ``smpy`` is not the CLI of the app it runs in (GH #929).

``uv run smpy`` falls through to whatever ``smpy`` is on ``PATH`` once the
project venv lost ``simple_module_cli`` (a plain ``uv sync`` used to drop it).
That is often an older ``uv tool install``-ed copy, which then scaffolds modules
pinned to its own version inside a newer app, or fails with errors that make no
sense inside the project. Reading the app's pins is cheap and local.
"""

from __future__ import annotations

import re
import sys
import tomllib
from collections.abc import Iterator
from pathlib import Path

import typer

from simple_module_cli.pins import PLACEHOLDER_VERSION

_FRAMEWORK_PIN = re.compile(r"^\s*simple[-_]module[-_][a-z0-9_-]+\s*==\s*([^\s;,\[]+)", re.I)

# Commands that legitimately run a CLI of another version than the app's:
# `new` makes an app, `update`/`package-update` change its pins.
_EXEMPT_COMMANDS = frozenset({"new", "update", "package-update"})


def _requirements(doc: dict) -> Iterator[str]:
project = doc.get("project", {})
yield from project.get("dependencies", [])
for extra in project.get("optional-dependencies", {}).values():
yield from extra
for group in doc.get("dependency-groups", {}).values():
yield from group


def _pinned_version(pyproject: Path) -> str | None:
try:
doc = tomllib.loads(pyproject.read_text(encoding="utf-8"))
except (OSError, tomllib.TOMLDecodeError):
return None
for requirement in _requirements(doc):
match = _FRAMEWORK_PIN.match(requirement) if isinstance(requirement, str) else None
if match:
return match.group(1)
return None


def app_framework_pin(start: Path) -> tuple[Path, str] | None:
"""``(project root, version)`` of the nearest project pinning the framework with ``==``.

A ``smpy new`` app pins every ``simple_module_*`` package to one version, in
the root ``pyproject.toml`` and (workspace mode) ``host/pyproject.toml``.
Range requirements, such as this repository's own, are not pins.
"""
current = start.resolve()
for candidate in (current, *current.parents):
for pyproject in (candidate / "pyproject.toml", candidate / "host" / "pyproject.toml"):
version = _pinned_version(pyproject) if pyproject.is_file() else None
if version is not None:
return candidate, version
return None


def running_cli() -> str:
"""Where the running ``smpy`` lives, for messages."""
return str(Path(sys.argv[0]).resolve()) if sys.argv and sys.argv[0] else sys.executable


def warn_if_not_the_apps_cli(command: str | None, current: str, start: Path) -> None:
"""One stderr warning when the project pins another framework version than this CLI's."""
if command in _EXEMPT_COMMANDS or current == PLACEHOLDER_VERSION:
return
found = app_framework_pin(start)
if found is None or found[1] == current:
return
root, pinned = found
typer.echo(
f"WARNING: this project ({root}) pins the framework to {pinned}, but this smpy is "
f"{current} ({running_cli()}).\n"
" Use the project's own CLI: `uv sync --all-packages`, then `uv run smpy ...`.",
err=True,
)
Loading
Loading