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

- `users`: Microsoft sign-in is OpenID Connect. It runs authorization-code + PKCE (S256) + nonce on the tenant's v2.0 endpoints and takes the identity from the validated ID token (RS256 against Entra's JWKS, exact issuer, `aud`/`azp`, `exp`/`iat`, nonce) instead of Graph `/me`. A tenant GUID also requires the token's `tid` to match, `organizations` refuses personal accounts and `consumers` accepts only them. The linked account id keeps the value Graph returned, so existing links keep matching; the email is the optional `upn` claim when present, else `preferred_username` (the UPN for members; add the `upn` optional claim if email is an alternate login ID). The trusted-tenant policy (#873) now also treats an `idp` claim naming another issuer as a guest, besides `#EXT#`. The OAuth callback passes the whole token response to `OAuthProvider.get_identity(token, login)` and keeps a per-login PKCE verifier and nonce in the session for providers that use them. **Behaviour change:** the Entra app registration needs the `openid`, `profile` and `email` delegated permissions (usually present by default); Graph `User.Read` is no longer requested. Code that calls `OAuthProvider.get_identity` with an access-token string must pass the token response dict (#876).

### Fixed

- `/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).

## [0.0.45] — 2026-11-11

### Fixed
Expand Down
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -248,8 +248,8 @@ Per-middleware detail: `docs/framework/middleware.md`,
`SidebarLayout` renders the menu its `menuKey` names, so a page left on
`AuthenticatedLayout` after its item moved shows a sidebar without it.
`group=` sub-clusters inside a sidebar (`Access`, `Appearance`, `System`).
`/admin` itself is a host route (`host/routes.py`) rendered from the
`adminSidebar` shared prop; old URLs 301 from `host/routes_legacy.py`.
`/admin` itself ships with `simple_module_hosting` (`admin_overview/`, mounted
by `create_app` like `/setup`) and renders the `adminSidebar` shared prop; old URLs 301 from `host/routes_legacy.py`.
`/api/*` paths never move.

**Inertia.** `inertia.render("<MetaName>/<Page>")` maps to
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -276,7 +276,7 @@ of them: a host that ships only `keycloak` (or only `oidc`) keeps it regardless
Either use the CLI:

```bash
uv run smpy users create-admin --email admin@example.com --password changeme
uv run smpy users create-admin --email admin@example.com
```

Or let the app bootstrap it automatically on first boot by setting env vars **before** running `make migrate && make dev`:
Expand Down
1 change: 1 addition & 0 deletions biome.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
"modules/*/*/**/components/**",
"modules/*/tests-js/**",
"framework/hosting/simple_module_hosting/setup_wizard/**",
"framework/hosting/simple_module_hosting/admin_overview/**",
"framework/hosting/tsconfig.json",
"!.claude",
"!**/*.md",
Expand Down
4 changes: 3 additions & 1 deletion docs/guide/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,9 +107,11 @@ Or run the whole stack in containers — `make docker-up` builds the image (`doc
If you included the `users` module:

```bash
uv run smpy users create-admin --email admin@example.com --password changeme
uv run smpy users create-admin --email admin@example.com
```

It prompts for the password; `--password` is for scripts and ends up in your shell history.

Or set bootstrap env vars so the admin is auto-created on first boot:

```bash
Expand Down
17 changes: 11 additions & 6 deletions docs/guide/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,11 @@ The API and Vite dev servers start side by side. Visit:
Until an administrator exists, every page redirects to the `/setup` wizard, which asks for one. To create it from a terminal instead (from inside `myapp`):

```bash
uv run smpy users create-admin --email admin@example.com --password changeme
uv run smpy users create-admin --email admin@example.com
```

It prompts for the password without echoing it. Pick a real one (a passphrase such as `correct-horse-battery-staple` is fine locally); `--password` exists for scripts, but it lands in your shell history.

Sign in at `/users/login` and you land on the dashboard.

## 5. Scaffold a new module
Expand Down Expand Up @@ -81,24 +83,27 @@ make migrate
Restart `make dev` (modules are discovered at boot). Then:

```bash
curl http://localhost:8000/api/orders
# → [] (200)
curl -i http://localhost:8000/api/orders
# → 401 {"detail":"Not authenticated"}
```

Visit `http://localhost:8000/orders` — you see the `Browse` page with an empty list and a "Create" button. The sidebar menu now includes an **Orders** entry (registered via `register_menu_items`).
The scaffold guards every route with the module's `orders.*` permissions, so an anonymous request is refused. Sign in as the admin and visit `http://localhost:8000/orders/` — you see the `Browse` page with an empty list and a "Create" button. The sidebar menu now includes an **Orders** entry (registered via `register_menu_items`).

## 8. Run the tests

```bash
uv run pytest
```

Single file:
Just the new module, or a single file:

```bash
uv run pytest modules/orders/tests/test_orders.py -v
uv run pytest modules/orders
uv run pytest modules/orders/tests/web/crud/test_orders_crud.py -v
```

The scaffold writes `modules/orders/tests/web/crud/test_orders_crud.py` (REST and page endpoints), `modules/orders/tests/core/module/test_orders_module.py` and `modules/orders/tests/core/contracts/test_orders_schemas.py`.

## What just happened

- **Discovery** — the `simple_module` entry point pointed Python's installer at `orders.module:OrdersModule`. `discover_modules()` loaded it, topologically sorted against every other installed module, and invoked `register_*` hooks in order.
Expand Down
4 changes: 2 additions & 2 deletions docs/modules/users.md
Original file line number Diff line number Diff line change
Expand Up @@ -328,10 +328,10 @@ undo the committed account; these callbacks do not retry mail delivery.

## CLI

- `smpy users create-admin --email <e> --password <p> [--full-name <name>] [--force]` — creates (or, with `--force`, updates) an admin user. Idempotent: re-running with the same email is a no-op without `--force`.
- `smpy users create-admin --email <e> [--password <p>] [--full-name <name>] [--force]` — creates (or, with `--force`, updates) an admin user. `--password` is prompted for (hidden) when omitted. Idempotent: re-running with the same email is a no-op without `--force`.

```bash
uv run smpy users create-admin --email admin@example.com --password changeme
uv run smpy users create-admin --email admin@example.com
```

Programmatically:
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 @@ -71,7 +71,7 @@ When a module declares a `simple_module_cli.cli_plugins` entry point, the CLI mo
`smpy users create-admin` is contributed by the `users` module as a `smpy users` subcommand:

```bash
uv run smpy users create-admin --email admin@example.com --password changeme
uv run smpy users create-admin --email admin@example.com
```

## Scaffolded-app Makefile
Expand Down
23 changes: 23 additions & 0 deletions docs/superpowers/plans/2026-11-11-app-dx-914-919.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Plan: first-run app fixes #914–#919

Design: `docs/superpowers/specs/2026-11-11-app-dx-914-919-design.md`. Four PRs, in order; each in its own worktree off `origin/main`, TDD, then `/ship`.

## PR 1 — #914, #919
1. Test: a scaffolded host has no `/admin` code and `gen-pages` registers `Admin/Overview` (`framework/cli/tests/test_scaffolded_host_admin_overview.py`).
2. `simple_module_hosting/admin_overview/` (`PAGES_NAME`, `PAGE_OVERVIEW`, `routes.py`, `pages/Overview.tsx`); `framework_assets()` returns both framework frontends; `create_app` mounts it.
3. Strings `host.admin.*` → `hosting.admin.*` (en/de/es); `make gen-i18n`.
4. Drop the host copy; keep the access tests in `host/tests` (they sign in through `users`) on the plain `app` fixture; vitest for the page.
5. Lint configs (biome include, raw-fetch roots, hosting tsconfig comment); quickstart/installation/README password and path fixes; CHANGELOG; CLAUDE.md.

## PR 2 — #916, #915
1. Test: the scaffolded workspace root depends on the host through a workspace source; `smpy new` next steps say `make install`.
2. Test: `create-module` inside an app workspace prints the app flow.
3. Test: discovery reports a module installed after start as "restart `make dev`".

## PR 3 — #917
1. Tests: a fresh initial schema and an unrelated revision print no warning; a revision touching a table with an un-emitted expression index warns.
2. Re-emit before warning; one advice helper for the hook, SM026 and the `migrate` note.

## PR 4 — #918
1. Test: a scaffolded module's pages use `t(keys.<pkg>.…)` and pass the app's `tsc`.
2. Make the keyed pages the base templates; delete the `framework_repo` overlay copies; next-step text mentions `make gen-i18n`.
76 changes: 76 additions & 0 deletions docs/superpowers/specs/2026-11-11-app-dx-914-919-design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# First-run app fixes from the 0.0.45 field test (#914–#919)

Six issues filed against a fresh `smpy new` app, shipped as four PRs.

## PR 1 — `/admin` in every app; quickstart corrections (#914, #919)

**Problem.** The sidebar "Administration" link and the AdminLayout badge go to
`/admin`, which only this repo's host serves (`host/routes.py` `admin_overview`
+ `host/client_app/pages/Admin.tsx`); a scaffolded app 404s. The quickstart
promises it, documents `curl /api/orders` as `200 []` (it is 401), and names a
test file the scaffold does not write.

**Approach.** Move the admin overview into `simple_module_hosting`, exactly as
the setup wizard is (#351): `simple_module_hosting/admin_overview/` with the
route (same gating: signed in, and admin or holding any admin-sidebar entry)
and `pages/Overview.tsx`, mounted by `app_builder` and registered by
`gen-pages` like `Setup/Wizard`. Its three strings move from `host/locales` to
the `hosting` namespace (en/de/es). This repo's host drops its copy.
Rejected: copying the route, page and a `host/locales` catalog into the host
template (duplicates the gating per app, forces a host catalog).

**Docs (#919).** Quickstart step 4: `create-admin` without `--password` (it
prompts) and a passphrase example; step 7: anonymous `curl` returns 401, open
`/orders/` signed in instead; step 8: `modules/orders/tests/web/crud/test_orders_crud.py`
(and `uv run pytest modules/orders`); same password fix in `installation.md`.

**Tests.** Hosting route tests moved from `host/tests/test_admin_overview_access.py`;
a scaffold test that the app has no admin route of its own and `/admin`
renders for an admin.

## PR 2 — `uv sync` keeps the app installed; adding a module during `make dev` (#916, #915)

**#916.** The workspace root template gains a dependency on the host package
through `[tool.uv.sources] <host> = { workspace = true }`, so a plain `uv sync`
installs host and every module instead of uninstalling them. `smpy new` runs
and prints the workspace-correct install (`make install`); `create-module`
inside an app workspace prints the app flow (`smpy add …`, `make install`,
`make migration`, `make test`) instead of `cd module && uv sync --extra dev`.

**#915.** uvicorn's reloader keeps the `sys.path` it started with, so a module
installed after `make dev` started cannot be imported until a restart. When an
entry point is found but its package cannot be imported, discovery says so:
"installed after this process started — restart `make dev`" instead of the
misleading "No module named '<x>.module'". Rejected: re-reading `.pth` files at
reload (re-implements editable installs); a watcher that restarts the
supervisor (new dev dependency, more moving parts than the problem).

## PR 3 — SQLite expression-index warning (#917)

The autogenerate hook warns about every expression index in the metadata, before
the revision has re-emitted them, and points at a make target and doc that only
exist in this repo. Fix: re-emit first, then warn only about expression indexes
on tables the revision touches that it did not emit (so a fresh app's initial
schema and an unrelated module migration print nothing). One advice helper
for the three messages (autogenerate warning, SM026, `migrate` note): this
repo's make target and doc only when they exist, otherwise "verify with
`alembic upgrade heads` against a PostgreSQL `SM_DATABASE_URL`".

## PR 4 — generated module pages use their locale file (#918)

The base module templates hardcode English while shipping `locales/en.json`;
the `framework_repo` overlay already has keyed pages (`t(keys.<pkg>.…)`,
`useApiErrorToast`). Make the keyed pages the only pages and delete the
overlay copies. A scaffolded app generates `keys.<pkg>` with `make gen-i18n`
(also on dev boot); `create-module` / `smpy add` next steps say so.
**Risk:** a module scaffolded outside any app (standalone repo) has no host to
generate keys; if its `tsc` cannot pass, the standalone variant keeps
hardcoded strings and the README says how to switch.

## Decisions made

- Four PRs, in the order above (PR 1 also unblocks the quickstart's `/admin`).
- Admin overview strings become `hosting.admin.*`.
- #915 gets a precise error message, not automatic reloading.
- #917 keeps SM026 and the `migrate` note (SQLite really cannot verify), only
their advice changes.
38 changes: 38 additions & 0 deletions framework/cli/tests/test_scaffolded_host_admin_overview.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
"""A freshly scaffolded host serves ``/admin`` with no files of its own.

GH #914: the sidebar's "Administration" link and the AdminLayout badge point
at ``/admin``, but the route and page lived only in this repository's host, so
an app made by ``smpy new`` answered 404. The overview now ships with
``simple_module_hosting`` like the setup wizard: ``create_app`` mounts the
route and ``gen-pages`` registers the page.
"""

from __future__ import annotations

import json

from simple_module_hosting.admin_overview import PAGE_OVERVIEW, PAGES_NAME, pages_dir
from simple_module_hosting.manifest import write_module_pages_manifest


def test_scaffold_carries_no_admin_code_and_resolves_the_overview(tmp_path) -> None:
from simple_module_cli.scaffolding import create_host

dest = tmp_path / "demo"
create_host(dest, name="demo-host", modules=[])
client_app = dest / "client_app"

assert "/admin" not in (dest / "routes.py").read_text(encoding="utf-8")
assert not list((client_app / "pages").rglob("Admin*"))

write_module_pages_manifest([], client_app, repo_root=dest)

manifest = json.loads((client_app / "modules.manifest.json").read_text(encoding="utf-8"))
assert manifest[PAGES_NAME] == pages_dir().as_posix()
assert (pages_dir() / "Overview.tsx").is_file()
assert f"{PAGES_NAME}/Overview" == PAGE_OVERVIEW

generated = (client_app / "modules.generated.ts").read_text(encoding="utf-8")
assert f'"{PAGES_NAME}": import.meta.glob' in generated
css = (client_app / "modules.generated.css").read_text(encoding="utf-8")
assert f'@source "{pages_dir().as_posix()}/**/*.{{ts,tsx}}";' in css
4 changes: 3 additions & 1 deletion framework/core/simple_module_core/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,9 @@ def _database_dialect() -> str:


def _hosting_locales() -> Path | None:
"""The framework's own ``hosting`` catalog (setup wizard), found without importing it.
"""The framework's own ``hosting`` catalog, found without importing it.

It holds the setup wizard's and the admin overview's strings.

The running app's ``build_i18n_registry`` always adds it, so doctor must
too, or every ``hosting.*`` host override reads as unknown (SM027). Core
Expand Down
4 changes: 2 additions & 2 deletions framework/hosting/simple_module_hosting/_i18n_build.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,8 @@ def build_i18n_registry(
for namespace, locale_dir in mod.locale_dirs().items():
registry.add_source(namespace, locale_dir, audience=audience)

# The framework's own catalog — the setup wizard ships with this package,
# so its strings must too, whatever host is serving it.
# The framework's own catalog — the setup wizard and the admin overview ship
# with this package, so their strings must too, whatever host is serving it.
hosting_locales = Path(__file__).resolve().parent / "locales"
registry.add_source("hosting", hosting_locales)
extra_sources.append(("simple_module_hosting", "hosting", hosting_locales))
Expand Down
42 changes: 42 additions & 0 deletions framework/hosting/simple_module_hosting/admin_overview/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
"""The ``/admin`` overview, shipped with the framework.

The sidebar's "Administration" link and the AdminLayout badge point every app
at ``/admin``. The page used to live in this repository's own host, so an app
made by ``smpy new`` answered 404 there (GH #914). ``create_app`` now mounts
it for every host, the way it mounts the setup wizard (GH #351).

No module owns the admin section as a whole — it is assembled from whatever
modules happen to be installed — so the framework serves it rather than one
plugin claiming ``/admin`` as its ``view_prefix``.

The page is registered in ``modules.generated.ts`` under :data:`PAGES_NAME`,
like a module's ``pages/``, so a host's Vite build picks it up from the wheel.
"""

from __future__ import annotations

from pathlib import Path

#: The ``modules.generated.ts`` key the overview's pages are registered under.
PAGES_NAME = "Admin"

#: ``pages/Overview.tsx`` as an Inertia page key.
PAGE_OVERVIEW = f"{PAGES_NAME}/Overview"

_PACKAGE_DIR = Path(__file__).resolve().parent


def package_dir() -> Path:
"""The overview's frontend root."""
return _PACKAGE_DIR


def pages_dir() -> Path:
return _PACKAGE_DIR / "pages"


def mount_admin_overview(app) -> None:
"""Mount ``/admin``; every other ``/admin/*`` path belongs to a module."""
from simple_module_hosting.admin_overview.routes import router

app.include_router(router)
Original file line number Diff line number Diff line change
Expand Up @@ -58,21 +58,24 @@ function AdminPage() {

return (
<>
<Head title={t(keys.host.admin.title)} />
<PageShell title={t(keys.host.admin.title)} description={t(keys.host.admin.description)}>
<Head title={t(keys.hosting.admin.title)} />
<PageShell
title={t(keys.hosting.admin.title)}
description={t(keys.hosting.admin.description)}
>
{items.length === 0 ? (
<p className="text-sm text-muted-foreground">{t(keys.host.admin.empty)}</p>
<p className="text-sm text-muted-foreground">{t(keys.hosting.admin.empty)}</p>
) : (
<div className="space-y-8">
{grouped.map(([group, groupItems_]) => (
{grouped.map(([group, cards]) => (
<section key={group || 'ungrouped'}>
{group && (
<h2 className="mb-3 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
{group}
</h2>
)}
<div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
{groupItems_.map((item) => (
{cards.map((item) => (
<ToolCard key={item.url} item={item} />
))}
</div>
Expand Down
Loading
Loading