From 62a0484d7cb462c1066d6f16ba154d1e6ce69786 Mon Sep 17 00:00:00 2001 From: Anto Subash Date: Thu, 12 Nov 2026 16:10:21 +0100 Subject: [PATCH 1/5] fix(cli): keep a smpy new app installed under uv sync; say restart for modules added during make dev (#916, #915) Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4 --- docs/guide/installation.md | 4 +- docs/guide/quickstart.md | 6 +- .../cli/simple_module_cli/_add_install.py | 22 ++++++- framework/cli/simple_module_cli/cli.py | 48 +++++++++----- framework/cli/simple_module_cli/new.py | 7 +- .../templates/workspace/README.md.tpl | 6 +- .../templates/workspace/pyproject.toml.tpl | 7 +- .../tests/test_cli_add_workspace_member.py | 28 ++++++-- .../cli/tests/test_cli_app_install_flow.py | 64 +++++++++++++++++++ .../simple_module_core/_entry_point_errors.py | 24 +++++++ .../core/simple_module_core/discovery.py | 10 ++- .../test_core_discovery_stale_sys_path.py | 64 +++++++++++++++++++ skills/simple-module-cli/SKILL.md | 13 ++-- skills/simple-module-creating/SKILL.md | 4 +- 14 files changed, 263 insertions(+), 44 deletions(-) create mode 100644 framework/cli/tests/test_cli_app_install_flow.py create mode 100644 framework/core/simple_module_core/_entry_point_errors.py create mode 100644 framework/core/tests/test_core_discovery_stale_sys_path.py diff --git a/docs/guide/installation.md b/docs/guide/installation.md index ca5686ad6..58b8af53b 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -60,7 +60,7 @@ smpy new myapp --preset standard --with background_tasks,file_storage Dependencies between modules are resolved automatically — e.g. `users` always pulls in `auth`, and `file_storage` pulls in `settings`. The `settings` module ships only in the `full` preset (or when added explicitly with `--with settings`). -After scaffolding, `smpy new` runs `uv sync`, `npm install`, and `alembic upgrade heads` for you (skip with `--no-install` if you'd rather drive that yourself). +After scaffolding, `smpy new` runs `uv sync --all-packages` (`uv sync` for `--flat`), `npm install`, and `alembic upgrade heads` for you. With `--no-install` it prints those steps instead, starting with `make install`. ## Boot it @@ -202,7 +202,7 @@ Run `make kill` to free the app's API and Vite ports (`:8000` and the port in `S The DB is ahead of or behind the migration files. For a dev DB: `rm app.db && make migrate`. For Postgres: `docker compose down -v && docker compose up -d postgres && make migrate`. **Entry points aren't discovered after editing a module's `pyproject.toml`.** -Re-run `uv sync` — entry points are registered at install time, not at import time. +Re-run `make install` (`uv sync --all-packages`) — entry points are registered at install time, not at import time. Then restart `make dev`: a reload keeps the import path the server started with. ## Next steps diff --git a/docs/guide/quickstart.md b/docs/guide/quickstart.md index 759fbe7a7..208780e73 100644 --- a/docs/guide/quickstart.md +++ b/docs/guide/quickstart.md @@ -17,7 +17,7 @@ smpy new myapp --yes cd myapp ``` -`--yes` accepts the defaults (SQLite, no multi-tenancy, the `standard` preset: `auth`, `users`, `dashboard`, `permissions`). The CLI runs `uv sync`, `npm install`, and `alembic upgrade heads` for you. +`--yes` accepts the defaults (SQLite, no multi-tenancy, the `standard` preset: `auth`, `users`, `dashboard`, `permissions`). The CLI runs `uv sync --all-packages`, `npm install`, and `alembic upgrade heads` for you. For an interactive run with prompts, drop the `--yes`. For a preset + extras: `smpy new myapp --preset standard --with background_tasks,file_storage --yes`. @@ -67,7 +67,7 @@ This generates a publishable module at `modules/orders/` with a working CRUD sam The [first-module guide](/guide/first-module) shows how to grow it: your own fields, validation, a migration and tests. -`smpy add ../modules/orders --path host` adds the package to `host/pyproject.toml` as a uv workspace source and runs `uv sync`, which registers its entry point; the module is discovered on the next boot. In a `smpy new --flat` app the module is not a workspace member, so wire it with `smpy add ./modules/orders` instead. +`smpy add ../modules/orders --path host` adds the package to `host/pyproject.toml` as a uv workspace source and syncs the whole workspace from the app root (`uv sync --all-packages`, what `make install` runs), which registers its entry point; the module is discovered on the next boot. Don't run `uv sync` inside `modules/orders`: that syncs the module alone and uninstalls the rest of the app from the shared venv. In a `smpy new --flat` app the module is not a workspace member, so wire it with `smpy add ./modules/orders` instead. ## 6. Generate a migration @@ -80,7 +80,7 @@ make migrate ## 7. Hit the module -Restart `make dev` (modules are discovered at boot). Then: +Restart `make dev` (modules are discovered at start-up). The reload `make dev` does when files change is not enough: it keeps the import path it started with, so a module installed since then logs "installed but … cannot be imported in this process" until you restart. Then: ```bash curl -i http://localhost:8000/api/orders diff --git a/framework/cli/simple_module_cli/_add_install.py b/framework/cli/simple_module_cli/_add_install.py index 5579ac3ec..932ac8e2f 100644 --- a/framework/cli/simple_module_cli/_add_install.py +++ b/framework/cli/simple_module_cli/_add_install.py @@ -8,6 +8,8 @@ import typer +from simple_module_cli.uv_workspace import find_workspace_root + ExecRunner = Callable[[list[str], Path], int] @@ -28,6 +30,20 @@ def _default_exec_runner(cmd: list[str], cwd: Path) -> int: return subprocess.run(cmd, cwd=cwd, check=False).returncode +def _sync_command(project_dir: Path) -> tuple[list[str], Path]: + """How to sync after editing ``project_dir``'s pyproject. + + A host inside an app workspace shares one venv with the root's dev tools + and every module member. ``uv sync`` from ``host/`` would sync the host + alone and uninstall the rest (GH #916), so sync the workspace from its + root, as ``make install`` does. + """ + root = find_workspace_root(project_dir) + if root is not None and root != project_dir.resolve(): + return ["uv", "sync", "--all-packages"], root + return ["uv", "sync"], project_dir + + def _fail(message: str) -> typer.Exit: typer.echo(f"ERROR: {message}", err=True) return typer.Exit(code=1) @@ -40,8 +56,10 @@ def post_install( exec_runner: ExecRunner, ) -> None: """uv sync → gen-pages → sync-js-deps → entry-point check → reminders.""" - if exec_runner(["uv", "sync"], project_dir) != 0: - raise _fail("`uv sync` failed — pyproject was written; fix and re-run `uv sync`.") + sync_cmd, sync_dir = _sync_command(project_dir) + if exec_runner(sync_cmd, sync_dir) != 0: + shown = " ".join(sync_cmd) + raise _fail(f"`{shown}` failed — pyproject was written; fix and re-run `{shown}`.") if (project_dir / "client_app").is_dir(): exec_runner(["uv", "run", "smpy", "host", "gen-pages"], project_dir) exec_runner(["uv", "run", "smpy", "host", "sync-js-deps"], project_dir) diff --git a/framework/cli/simple_module_cli/cli.py b/framework/cli/simple_module_cli/cli.py index 3977152bf..92ff7463b 100644 --- a/framework/cli/simple_module_cli/cli.py +++ b/framework/cli/simple_module_cli/cli.py @@ -126,25 +126,36 @@ 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).""" +def _app_add_command(target: Path) -> str | None: + """``smpy add …`` wiring a module into its app's host, or None outside an app (GH #442).""" root = find_workspace_root(target.parent) if root is None: - return + return None host = root / "host" if not (host / "pyproject.toml").is_file() or not is_workspace_member(host, target): - return + return None 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 }" - ) + return f"smpy add {rel} --path {host_arg}" + + +def _echo_app_next_steps(add_command: str, slug: str) -> None: + """The module lives in an app's workspace: wire it in with the app's own commands. + + Never ``uv sync`` inside the module: that syncs the module alone and + uninstalls the rest of the app from the shared venv (GH #916). + """ + typer.echo("\nNext steps (from the app root):") + typer.echo(f" {add_command} # adds it as {{ workspace = true }}") + typer.echo(" make install") + typer.echo(f' make migration msg="add {slug}"') + typer.echo(" make migrate") + typer.echo(" make test") + typer.echo("Then restart `make dev`: modules are discovered at start-up, not on reload.") @app.command("create-module") @@ -193,14 +204,17 @@ 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") - typer.echo(" uv run pytest") - typer.echo(" npm install") - typer.echo(" npm run typecheck") - typer.echo(" uv run smpy module verify") + add_command = _app_add_command(target) + if add_command is not None: + _echo_app_next_steps(add_command, slug) + else: + typer.echo("\nNext steps:") + typer.echo(f" cd {target}") + typer.echo(" uv sync --extra dev") + typer.echo(" uv run pytest") + typer.echo(" npm install") + typer.echo(" npm run typecheck") + typer.echo(" uv run smpy module verify") typer.echo( "\nThe pages ship sample API types (pages/api.generated.ts). Once the host serves " "the module, refresh them after any endpoint change:\n" diff --git a/framework/cli/simple_module_cli/new.py b/framework/cli/simple_module_cli/new.py index 233a50fb6..7d84e3c1b 100644 --- a/framework/cli/simple_module_cli/new.py +++ b/framework/cli/simple_module_cli/new.py @@ -177,8 +177,7 @@ def new_project( typer.echo("\nNext steps:") typer.echo(f" cd {target}") if no_install: - typer.echo(" uv sync") - typer.echo(" npm install") + typer.echo(" make install") typer.echo(' make migration msg="initial schema"') typer.echo(" make migrate") typer.echo(" make dev") @@ -188,7 +187,9 @@ def new_project( return typer.echo("Installing dependencies...") - for cmd in (["uv", "sync"], ["npm", "install"]): + # What `make install` runs: a workspace syncs every member, not just the root. + uv_sync = ["uv", "sync"] if flat else ["uv", "sync", "--all-packages"] + for cmd in (uv_sync, ["npm", "install"]): if shutil.which(cmd[0]) is None: typer.echo( f"WARNING: '{cmd[0]}' not found on PATH; skipping `{' '.join(cmd)}`. " diff --git a/framework/cli/simple_module_cli/templates/workspace/README.md.tpl b/framework/cli/simple_module_cli/templates/workspace/README.md.tpl index 6ca4f2890..de0b0b710 100644 --- a/framework/cli/simple_module_cli/templates/workspace/README.md.tpl +++ b/framework/cli/simple_module_cli/templates/workspace/README.md.tpl @@ -67,8 +67,10 @@ make migration msg="add my-feature" && make migrate ## How the workspace fits together - **uv workspace** (`pyproject.toml` here): members are `host` and every - directory under `modules/*`. `uv sync --all-packages` installs them all - in editable mode against the host's venv. + directory under `modules/*`. `make install` (`uv sync --all-packages`) + installs them all in editable mode in one venv. The root depends on the + host, so a plain `uv sync` here installs the app too; never run `uv sync` + inside a module directory, which syncs that module alone. - **npm workspace** (`package.json` here): `host/client_app` and every module's frontend assets share one hoisted `node_modules`. Vite walks up from each `.tsx` file and finds React, Inertia, and shared UI diff --git a/framework/cli/simple_module_cli/templates/workspace/pyproject.toml.tpl b/framework/cli/simple_module_cli/templates/workspace/pyproject.toml.tpl index 868b631ba..88c495200 100644 --- a/framework/cli/simple_module_cli/templates/workspace/pyproject.toml.tpl +++ b/framework/cli/simple_module_cli/templates/workspace/pyproject.toml.tpl @@ -3,12 +3,17 @@ name = "{{HOST_PYPI_NAME}}" version = "0.1.0" description = "SimpleModule application workspace root" requires-python = ">=3.12" -dependencies = [] +# The app itself, so a plain `uv sync` here installs host and modules instead +# of uninstalling them (GH #916). `make install` adds the other members. +dependencies = ["{{HOST_PYPI_NAME}}-host"] # Workspace root: not built or installed itself. [tool.uv] package = false +[tool.uv.sources] +{{HOST_PYPI_NAME}}-host = { workspace = true } + # uv workspace — `host/` is the application; modules/* are workspace # members so you can iterate on them without publishing to PyPI. Add a # `[tool.uv.sources]` entry in host/pyproject.toml for each in-repo diff --git a/framework/cli/tests/test_cli_add_workspace_member.py b/framework/cli/tests/test_cli_add_workspace_member.py index 17c748689..8fa19f38d 100644 --- a/framework/cli/tests/test_cli_add_workspace_member.py +++ b/framework/cli/tests/test_cli_add_workspace_member.py @@ -8,7 +8,7 @@ import pytest import typer from simple_module_cli.add_cmd import run_add -from simple_module_cli.cli import _echo_workspace_hint +from simple_module_cli.cli import _app_add_command from simple_module_cli.git_source import parse_add_spec from simple_module_cli.uv_workspace import is_workspace_member @@ -92,7 +92,7 @@ def test_missing_path_error_names_the_resolution_base( def test_workspace_hint_inside_host_dir_prints_a_path_spec( - tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] + tmp_path: Path, monkeypatch: pytest.MonkeyPatch ) -> None: # GH #471: a bare "modules/x" would be parsed by `smpy add` as a PyPI requirement. (tmp_path / "pyproject.toml").write_text( @@ -104,9 +104,27 @@ def test_workspace_hint_inside_host_dir_prints_a_path_spec( _write_module(module) monkeypatch.chdir(tmp_path) - _echo_workspace_hint(module) + command = _app_add_command(module) - out = capsys.readouterr().out - spec = out.split("smpy add ", 1)[1].split(" --path", 1)[0] + assert command is not None + spec = command.split("smpy add ", 1)[1].split(" --path", 1)[0] assert spec == "./modules/forest_plots" assert parse_add_spec(spec).kind == "path" + + +def test_add_inside_an_app_workspace_syncs_the_whole_workspace(workspace: Path) -> None: + """GH #916: `uv sync` from host/ would uninstall the root's dev tools and other members.""" + _write_module(workspace / "modules" / "forest_plots") + calls: list[tuple[list[str], Path]] = [] + + def runner(cmd: list[str], cwd: Path) -> int: + calls.append((cmd, cwd)) + return 0 + + run_add( + "../modules/forest_plots", + pyproject=workspace / "host" / "pyproject.toml", + exec_runner=runner, + ) + + assert calls[0] == (["uv", "sync", "--all-packages"], workspace.resolve()) diff --git a/framework/cli/tests/test_cli_app_install_flow.py b/framework/cli/tests/test_cli_app_install_flow.py new file mode 100644 index 000000000..bed782411 --- /dev/null +++ b/framework/cli/tests/test_cli_app_install_flow.py @@ -0,0 +1,64 @@ +"""A ``smpy new`` app stays installed under plain uv commands (GH #916). + +The workspace root used to have no dependencies, so ``uv sync`` at the root, +or the ``uv sync --extra dev`` that ``create-module`` printed, uninstalled the +app's own modules from the shared venv. +""" + +from __future__ import annotations + +import tomllib +from pathlib import Path + +from simple_module_cli.cli import app +from typer.testing import CliRunner + + +def _new_app(tmp_path: Path) -> tuple[Path, str]: + target = tmp_path / "demo" + result = CliRunner().invoke( + app, ["new", "demo", "--yes", "--db", "sqlite", "--no-install", "--dest", str(target)] + ) + assert result.exit_code == 0, result.output + return target, result.output + + +def test_root_project_installs_the_host_through_a_workspace_source(tmp_path) -> None: + target, _ = _new_app(tmp_path) + root = tomllib.loads((target / "pyproject.toml").read_text(encoding="utf-8")) + host = tomllib.loads((target / "host" / "pyproject.toml").read_text(encoding="utf-8")) + host_name = host["project"]["name"] + + assert root["project"]["dependencies"] == [host_name] + assert root["tool"]["uv"]["sources"][host_name] == {"workspace": True} + + +def test_no_install_next_steps_use_make_install(tmp_path) -> None: + _, output = _new_app(tmp_path) + steps = output.split("Next steps:", 1)[1] + assert " make install\n" in steps + assert " uv sync\n" not in steps + assert " npm install\n" not in steps # make install runs it + + +def test_create_module_inside_an_app_prints_the_app_flow(tmp_path, monkeypatch) -> None: + target, _ = _new_app(tmp_path) + monkeypatch.chdir(target) + result = CliRunner().invoke(app, ["create-module", "notes", "--dest", "modules/notes"]) + + assert result.exit_code == 0, result.output + steps = result.output.split("Next steps", 1)[1] + assert "smpy add ../modules/notes --path host" in steps + assert "make install" in steps + assert 'make migration msg="add notes"' in steps + assert "make test" in steps + assert "restart `make dev`" in steps + assert "uv sync --extra dev" not in result.output + + +def test_create_module_outside_an_app_keeps_the_package_flow(tmp_path, monkeypatch) -> None: + monkeypatch.chdir(tmp_path) + result = CliRunner().invoke(app, ["create-module", "notes", "--dest", "notes"]) + + assert result.exit_code == 0, result.output + assert "uv sync --extra dev" in result.output diff --git a/framework/core/simple_module_core/_entry_point_errors.py b/framework/core/simple_module_core/_entry_point_errors.py new file mode 100644 index 000000000..ecc2a3c16 --- /dev/null +++ b/framework/core/simple_module_core/_entry_point_errors.py @@ -0,0 +1,24 @@ +"""Telling an unimportable module entry point apart from a broken module.""" + +from __future__ import annotations + + +def own_package_missing(ep, exc: BaseException) -> bool: + """Whether the entry point's own package, not a dependency, is unimportable. + + A package installed after this process started looks like that: the entry + point is listed (metadata is read fresh) but ``sys.path`` was fixed at + start-up, so an editable install's ``.pth`` entry is not on it (GH #915). + """ + if not isinstance(exc, ModuleNotFoundError) or not exc.name: + return False + target = getattr(ep, "module", "") or "" + return target == exc.name or target.startswith(f"{exc.name}.") + + +def stale_path_message(ep, exc: ModuleNotFoundError) -> str: + return ( + f"Module entry point '{ep.name}' is installed but {exc.name!r} cannot be imported " + "in this process. If it was added after the server started (smpy add, uv sync), " + "restart `make dev`: a reload keeps the old import path" + ) diff --git a/framework/core/simple_module_core/discovery.py b/framework/core/simple_module_core/discovery.py index 82e44219a..a6e28f748 100644 --- a/framework/core/simple_module_core/discovery.py +++ b/framework/core/simple_module_core/discovery.py @@ -6,6 +6,7 @@ from collections.abc import Sequence from importlib.metadata import entry_points +from simple_module_core._entry_point_errors import own_package_missing, stale_path_message from simple_module_core.dotenv import env_str, load_dotenv_into_environ from simple_module_core.exceptions import ( CircularDependencyError, @@ -63,10 +64,10 @@ def discover_modules( # Imported here to avoid a circular import at module load time. from simple_module_core.versioning import check_framework_compatibility - def fail(msg: str, exc: BaseException | None = None) -> None: + def fail(msg: str, exc: BaseException | None = None, *, traceback: bool = True) -> None: if strict: raise InvalidModuleError(msg) from exc - if exc is not None: + if exc is not None and traceback: logger.exception("%s — skipping", msg) else: logger.error("%s — skipping", msg) @@ -79,7 +80,10 @@ def fail(msg: str, exc: BaseException | None = None) -> None: try: module_cls = ep.load() except Exception as exc: - fail(f"Failed to load module entry point '{ep.name}': {exc}", exc) + if own_package_missing(ep, exc): + fail(stale_path_message(ep, exc), exc, traceback=False) + else: + fail(f"Failed to load module entry point '{ep.name}': {exc}", exc) continue try: diff --git a/framework/core/tests/test_core_discovery_stale_sys_path.py b/framework/core/tests/test_core_discovery_stale_sys_path.py new file mode 100644 index 000000000..f2f2eec9c --- /dev/null +++ b/framework/core/tests/test_core_discovery_stale_sys_path.py @@ -0,0 +1,64 @@ +"""A module installed after the process started reports "restart", not a crash. + +GH #915: with ``make dev`` running, ``smpy add`` installs a module as an +editable package. uvicorn's reloader keeps the ``sys.path`` it started with, +so the new entry point is listed but its package cannot be imported until a +restart. Discovery used to log ``No module named 'notes.module'`` with a +traceback, which reads as a broken module. +""" + +from __future__ import annotations + +import logging + +import pytest +import simple_module_core.discovery as discovery_mod +from simple_module_core.discovery import InvalidModuleError, discover_modules + + +class _EntryPoint: + def __init__(self, name: str, module: str, exc: Exception) -> None: + self.name = name + self.module = module + self._exc = exc + + def load(self): + raise self._exc + + +def _missing(name: str) -> ModuleNotFoundError: + return ModuleNotFoundError(f"No module named {name!r}", name=name) + + +@pytest.mark.parametrize("missing", ["notes", "notes.module"]) +def test_unimportable_own_package_says_restart(monkeypatch, caplog, missing) -> None: + ep = _EntryPoint("notes", "notes.module", _missing(missing)) + monkeypatch.setattr(discovery_mod, "entry_points", lambda group: [ep]) + + with caplog.at_level(logging.ERROR, logger="simple_module_core.discovery"): + assert discover_modules(strict=False) == [] + + (record,) = [r for r in caplog.records if "notes" in r.getMessage()] + assert "restart" in record.getMessage() + assert record.exc_info is None # no traceback: the module is not broken + + +def test_strict_mode_still_refuses(monkeypatch) -> None: + ep = _EntryPoint("notes", "notes.module", _missing("notes.module")) + monkeypatch.setattr(discovery_mod, "entry_points", lambda group: [ep]) + + with pytest.raises(InvalidModuleError, match="restart"): + discover_modules(strict=True) + + +def test_a_missing_third_party_import_is_still_a_failure(monkeypatch, caplog) -> None: + """The module's own code importing something absent is a real bug.""" + ep = _EntryPoint("notes", "notes.module", _missing("somelib")) + monkeypatch.setattr(discovery_mod, "entry_points", lambda group: [ep]) + + with caplog.at_level(logging.ERROR, logger="simple_module_core.discovery"): + discover_modules(strict=False) + + (record,) = [r for r in caplog.records if "notes" in r.getMessage()] + assert "restart" not in record.getMessage() + assert record.exc_info is not None diff --git a/skills/simple-module-cli/SKILL.md b/skills/simple-module-cli/SKILL.md index c5c3a4274..3a512ae08 100644 --- a/skills/simple-module-cli/SKILL.md +++ b/skills/simple-module-cli/SKILL.md @@ -15,7 +15,7 @@ The `smpy` command is provided by `simple_module_cli` (installed as a dep of `si |---|---| | `smpy new ` | Greenfield: scaffold a complete app (host + selected modules) in one shot, with an interactive wizard for DB / tenancy / module preset | | `smpy create-host ` | You want just a bare host project; you'll add modules later by `pip install`-ing them | -| `smpy create-module ` | You're authoring a publishable module package (separate repo, distributed via PyPI) | +| `smpy create-module ` | You're adding a module to a `smpy new` app (`--dest modules/`), or authoring a publishable module package in its own repo | | `smpy package-update` | Bump every `simple_module_*` / `simple-module-*` dependency, optional extra and dependency group to its latest non-yanked PyPI release, and `@simple-module-py/*` npm pins to the same core version (workspace/path/git/URL sources are left untouched) | | `smpy migrations prepare --head