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
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ All notable changes to this project are documented in this file. The format is b

- `/admin` works in every app. The admin overview that the sidebar's "Administration" link and the AdminLayout badge open lived only in this repository's host, so an app made by `smpy new` answered 404 there. It now ships with `simple_module_hosting` (`simple_module_hosting.admin_overview`), mounted by `create_app` and registered by `gen-pages` as the `Admin/Overview` page, exactly like the `/setup` wizard; admission is unchanged (an admin, or anyone with an admin sidebar entry). Its strings moved from the `host` namespace to `hosting.admin.*`. An existing app needs nothing beyond upgrading and running `smpy gen-pages` (a dev boot does it); a host that copied this repository's `/admin` route and `pages/Admin.tsx` can delete both, since `create_app`'s route is matched first. `simple_module_hosting.assets.framework_assets()` now returns a list, and `gen-pages` refuses a module whose `ModuleMeta.name` is `Admin` or `Setup`, which would have hidden that module's pages (#914).
- The quickstart matches what a new app does: an anonymous `curl /api/orders` answers 401 (the scaffold guards the API with `orders.*` permissions), the single-file test example names `tests/web/crud/test_orders_crud.py`, and `smpy users create-admin` is shown without `--password`, so it prompts instead of putting a weak password in shell history (#919).
- A `smpy new` app stays installed under plain uv commands. The workspace root now depends on the host (`<app>-host`, a `{ workspace = true }` source), so `uv sync` at the root installs the app instead of uninstalling it. `smpy add … --path host` inside an app, where the host is a workspace member, syncs the whole workspace from the root (`uv sync --all-packages`, as `make install` does) instead of syncing `host/` alone, which removed the root's dev tools and other modules. `smpy create-module` inside an app prints the app's steps (`smpy add`, `make install`, `make migration`, `make migrate`, `make test`, restart `make dev`) instead of `uv sync --extra dev` in the module, which uninstalled the rest of the app; `--no-install` prints `make install`. An existing app can add `dependencies = ["<app>-host"]` and `[tool.uv.sources] <app>-host = { workspace = true }` to its root `pyproject.toml` (#916).
- A module installed while `make dev` runs is reported as such. The reload keeps the import path the server started with, so its package cannot be imported until a restart; discovery used to log `No module named '<x>.module'` with a traceback, as if the module were broken. It now logs that the entry point is installed but its package cannot be imported in this process, and to restart `make dev` (`strict` discovery still refuses it). A missing third-party import inside a module is still reported with its traceback (#915).

## [0.0.45] — 2026-11-11

Expand Down
2 changes: 1 addition & 1 deletion docs/guide/first-module.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ smpy create-module orders --dest modules/orders
smpy add ../modules/orders --path host
```

This creates `modules/orders/` with a working CRUD implementation against a single-field `Order` table. `smpy add` wires it into the host: it adds `simple_module_orders` to `host/pyproject.toml` as a uv workspace source (`{ workspace = true }`), runs `uv sync` and regenerates the page manifest. `create-module` prints this same command. In a `smpy new --flat` app the module is not a workspace member, so wire it with `smpy add ./modules/orders` instead. Open the generated files in your editor — you'll see the full file layout described in [project structure](/guide/project-structure).
This creates `modules/orders/` with a working CRUD implementation against a single-field `Order` table. `smpy add` wires it into the host: it adds `simple_module_orders` to `host/pyproject.toml` as a uv workspace source (`{ workspace = true }`), syncs the whole workspace from the app root (`uv sync --all-packages`) and regenerates the page manifest. `create-module` prints this same command. In a `smpy new --flat` app the module is not a workspace member, so wire it with `smpy add ./modules/orders` instead. Open the generated files in your editor — you'll see the full file layout described in [project structure](/guide/project-structure).

New modules put shared settings and constants in `core/`, HTTP code in `web/`,
and reusable frontend code in `ui/`. Root lookup paths (`models.py`, `contracts/`,
Expand Down
4 changes: 2 additions & 2 deletions docs/guide/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
6 changes: 3 additions & 3 deletions docs/guide/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/make-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ smpy --help

| Command | What |
|---|---|
| `smpy add <spec>` | Add a module dependency and wire it up. `<spec>` is a PyPI requirement, a `git+URL[@ref][#subdirectory=dir]`, or a local path. Writes `pyproject.toml`, then runs `uv sync` + `gen-pages` unless `--no-sync`. |
| `smpy add <spec>` | Add a module dependency and wire it up. `<spec>` is a PyPI requirement, a `git+URL[@ref][#subdirectory=dir]`, or a local path. Writes `pyproject.toml`, then runs `uv sync` + `gen-pages` unless `--no-sync` (inside a workspace app the sync runs from the app root as `uv sync --all-packages`). |
| `smpy update [name]` | Update git-sourced modules to their newest release tag. Omit the name to update every git-sourced module; `--dry-run` previews. |

`smpy add` handles a repo containing several modules: `--module a,b` picks specific dist names and `--all` takes every module it finds.
Expand Down
28 changes: 26 additions & 2 deletions framework/cli/simple_module_cli/_add_install.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@

import typer

from simple_module_cli.uv_workspace import find_workspace_root, is_workspace_member

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


Expand All @@ -28,6 +30,24 @@ 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()
and is_workspace_member(project_dir, project_dir)
):
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)
Expand All @@ -40,8 +60,12 @@ 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}` from {sync_dir}."
)
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)
Expand Down
53 changes: 33 additions & 20 deletions framework/cli/simple_module_cli/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -126,25 +126,35 @@ 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 }"
)
# The steps are printed "from the app root", so name the host relative to it.
host_arg = host.resolve().relative_to(root.resolve()).as_posix()
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")
Expand Down Expand Up @@ -193,14 +203,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"
Expand Down
7 changes: 4 additions & 3 deletions framework/cli/simple_module_cli/new.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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)}`. "
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,19 @@ 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 the host's dependencies
# (every module wired into it) instead of uninstalling them (GH #916). The host
# is `package = false`, so it is not installed itself. `make install` also
# syncs the members the host does not list yet.
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
Expand Down
40 changes: 35 additions & 5 deletions framework/cli/tests/test_cli_add_workspace_member.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,9 @@

import pytest
import typer
from simple_module_cli._add_install import _sync_command
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

Expand Down Expand Up @@ -92,7 +93,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(
Expand All @@ -104,9 +105,38 @@ 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
assert command.endswith("--path host") # printed for the app root
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())


def test_add_in_a_project_outside_the_workspace_members_syncs_it_alone(tmp_path: Path) -> None:
"""A flat app nested under an unrelated workspace must not sync that workspace."""
(tmp_path / "pyproject.toml").write_text(WORKSPACE, encoding="utf-8")
app_dir = tmp_path / "elsewhere" / "app"
app_dir.mkdir(parents=True)
(app_dir / "pyproject.toml").write_text(HOST, encoding="utf-8")

assert _sync_command(app_dir) == (["uv", "sync"], app_dir)
Loading
Loading