simple-module-hosting 0.0.1__py3-none-any.whl

simple_module_hosting/app_builder.py

@@ -0,0 +1,281 @@
+"""Application builder — discovers modules, wires everything, returns a FastAPI app."""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import APIRouter, FastAPI
+from fastapi.staticfiles import StaticFiles
+from simple_module_core.diagnostics import DiagnosticLevel, print_diagnostics, run_diagnostics
+from simple_module_core.discovery import discover_modules, topological_sort
+from simple_module_core.events import EventBus
+from simple_module_core.feature_flags import FeatureFlagRegistry
+from simple_module_core.health import HealthRegistry
+from simple_module_core.menu import MenuRegistry
+from simple_module_core.permissions import PermissionRegistry
+from simple_module_core.services import Services
+from simple_module_db.listeners import register_listeners
+from simple_module_db.session import init_db
+
+from simple_module_hosting._inertia_setup import setup_inertia
+from simple_module_hosting._phase_helpers import (
+    check_settings_registration,
+    install_middleware,
+    mount_module_static_dirs,
+    register_exception_handlers,
+)
+from simple_module_hosting.health import router as health_router
+from simple_module_hosting.i18n_manifest import build_i18n_registry, emit_frontend_types
+from simple_module_hosting.migrations import check_migrations
+from simple_module_hosting.settings import Settings
+
+logger = logging.getLogger(__name__)
+
+_APP_TITLE = "SimpleModule"
+_APP_VERSION = "0.1.0"
+_DOCS_URL = "/api/docs"
+_REDOC_URL = "/api/redoc"
+_STATIC_MOUNT_PATH = "/static"
+_STATIC_DIR_NAME = "static"
+_ENV_PROJECT_ROOT = "SM_PROJECT_ROOT"
+
+
+def _resolve_project_root() -> Path:
+    """Return the project root directory.
+
+    Prefers the ``SM_PROJECT_ROOT`` environment variable (set by
+    ``host/main.py``) so the framework works even when installed from a
+    wheel into ``site-packages`` — in that layout the fallback walk-up
+    below would escape the package into ``site-packages/..`` and miss
+    ``host/static`` entirely.
+
+    Falls back to ``parents[3]`` for the workspace-install dev loop
+    (simple_module_hosting/ → hosting/ → framework/ → project root).
+    """
+    override = os.environ.get(_ENV_PROJECT_ROOT)
+    if override:
+        return Path(override)
+    return Path(__file__).resolve().parents[3]
+
+
+_PROJECT_ROOT = _resolve_project_root()
+
+
+def wire_module_routes(app: FastAPI, module) -> None:
+    """Attach a module's API + view routers to ``app`` using its Meta prefixes.
+
+    The single canonical implementation so ``create_app`` and the test harness
+    in ``simple_module_testing`` stay in lockstep if ``ModuleBase`` ever gains
+    a new router type.
+    """
+    api_router = APIRouter(prefix=module.meta.route_prefix, tags=[module.meta.name])
+    view_router = APIRouter(prefix=module.meta.view_prefix, tags=[f"{module.meta.name} Views"])
+    module.register_routes(api_router, view_router)
+    app.include_router(api_router)
+    app.include_router(view_router)
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    """Build and configure the full FastAPI application.
+
+    Boot sequence:
+      1. Load settings & discover modules
+      2. Run diagnostics (dev only)
+      3. Create FastAPI app & store framework state
+      4. Module settings (register_settings)
+      5. Module registrations (menu, permissions, flags, events, health)
+      6. Initialize database
+      7. Inertia setup & exception handlers (register_exception_handlers)
+      8. Middleware pipeline (register_middleware)
+      9. Routes (register_routes), health endpoints, static files
+    """
+    settings = settings or Settings()
+
+    # ── Phase 1: Discover modules ──────────────────────────
+    # Production: any bad module (import error, missing meta, wrong base
+    # class) fails the boot immediately with a clear message — better than
+    # silently shipping a partial app. Dev keeps the lenient default.
+    modules = discover_modules(
+        enabled=settings.modules_enabled,
+        strict=not settings.is_development,
+    )
+    modules = topological_sort(modules)
+    logger.info(
+        "Loaded %d module(s): %s",
+        len(modules),
+        ", ".join(m.meta.name for m in modules),
+    )
+
+    # Build the i18n registry up front so diagnostics can validate key parity
+    # against host/ui locales, not just module-contributed ones.
+    i18n_registry, i18n_extra = build_i18n_registry(settings, modules, _PROJECT_ROOT)
+
+    # ── Phase 2: Run diagnostics (dev only) ────────────────
+    if settings.is_development:
+        diagnostics = run_diagnostics(
+            modules,
+            i18n_supported_locales=settings.i18n_supported_locales,
+            i18n_default_locale=settings.i18n_default_locale,
+            i18n_extra_sources=i18n_extra,
+        )
+        errors = [d for d in diagnostics if d.level == DiagnosticLevel.ERROR]
+        if diagnostics:
+            print_diagnostics(diagnostics)
+        if errors:
+            raise SystemExit(f"Module diagnostics: {len(errors)} error(s). Fix before continuing.")
+
+        # Emit frontend module-pages manifest so Vite can find pages shipped
+        # inside pip-installed module wheels. See scaffolding.py.
+        try:
+            from simple_module_hosting.scaffolding import write_module_pages_manifest
+
+            client_app = _PROJECT_ROOT / "host" / "client_app"
+            if client_app.is_dir():
+                write_module_pages_manifest(modules, client_app)
+        except Exception:
+            logger.exception("Failed to write module pages manifest — frontend may miss pages")
+
+        emit_frontend_types(i18n_registry, _PROJECT_ROOT)
+
+    # ── Phase 3: Create FastAPI app ────────────────────────
+    menu_registry = MenuRegistry()
+    perm_registry = PermissionRegistry()
+    ff_registry = FeatureFlagRegistry()
+    event_bus = EventBus()
+    health_registry = HealthRegistry()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+        app.state.migration = await check_migrations(app.state.sm.db.engine)
+
+        # Hydrate all registered settings from DB before any module
+        # on_startup hook runs, so startup code sees DB-backed values.
+        # Importlib keeps plugin names out of the framework AST (SM009).
+        if hasattr(app.state, "settings"):
+            import importlib
+
+            from simple_module_hosting._hydrate_step import hydrate_all
+
+            service_cls = importlib.import_module("settings.service").SettingService
+            store_cls = importlib.import_module("settings.store").SettingsStore
+
+            async with app.state.sm.db.session_factory() as session:
+                await hydrate_all(app, store_cls(service_cls(session)))
+
+        for mod in modules:
+            await mod.on_startup(app)
+        yield
+        for mod in reversed(modules):
+            await mod.on_shutdown(app)
+        await app.state.sm.db.engine.dispose()
+
+    app = FastAPI(
+        title=_APP_TITLE,
+        version=_APP_VERSION,
+        docs_url=_DOCS_URL if settings.is_development else None,
+        redoc_url=_REDOC_URL if settings.is_development else None,
+        lifespan=lifespan,
+    )
+
+    # ── Phase 4: Module settings ───────────────────────────
+    for mod in modules:
+        mod.register_settings(app)
+
+    # Register host-level settings under package="host" (DB-backed). The
+    # Settings module must already have run register_settings (topo order
+    # puts it early; its meta.depends_on = [] so it's among the first).
+    # When the Settings module isn't enabled, there's no registry to
+    # register against — skip quietly.
+    #
+    # We resolve `settings.registration` via importlib rather than a plain
+    # `from settings.registration import ...`: the SM009 coupling check is
+    # AST-based and forbids any static import of a plugin package name
+    # from within framework/* code. Dynamic resolution keeps the framework
+    # AST plugin-free while still hitting the real helper at runtime.
+    if hasattr(app.state, "settings"):
+        import importlib
+        from dataclasses import dataclass as _dataclass
+
+        from simple_module_hosting.host_settings import HostSettings
+
+        _register_module_settings = importlib.import_module(
+            "settings.registration"
+        ).register_module_settings
+
+        @_dataclass
+        class _HostServices:
+            settings: HostSettings
+
+        _register_module_settings(app, "host", HostSettings, lambda s: _HostServices(settings=s))
+
+    if settings.is_development:
+        settings_diagnostics = check_settings_registration(app, modules)
+        if settings_diagnostics:
+            print_diagnostics(settings_diagnostics)
+
+    # ── Phase 5: Module registrations ──────────────────────
+    for mod in modules:
+        mod.register_menu_items(menu_registry)
+        mod.register_permissions(perm_registry)
+        mod.register_feature_flags(ff_registry)
+        mod.register_event_handlers(event_bus)
+        mod.register_health_checks(health_registry)
+
+    logger.info(
+        "Registered %d menu items, %d permissions, %d feature flags, %d health checks",
+        len(menu_registry.all_items),
+        len(perm_registry.all_permissions),
+        len(ff_registry.all_flags),
+        len(health_registry.all_checks),
+    )
+
+    # ── Phase 6: Initialize database ───────────────────────
+    db_state = init_db(
+        settings.database_url,
+        echo=settings.debug,
+        pool_size=settings.db_pool_size,
+        max_overflow=settings.db_max_overflow,
+        pool_pre_ping=settings.db_pool_pre_ping,
+        pool_recycle=settings.db_pool_recycle,
+    )
+    register_listeners(db_state)
+
+    # ── Phase 7: Inertia + exception handlers ──────────────
+    inertia_config = setup_inertia(app, settings, modules, _PROJECT_ROOT)
+    if inertia_config is None:
+        raise RuntimeError("Inertia not configured — no template directories available")
+    register_exception_handlers(app, modules)
+
+    # ── Phase 8: Middleware pipeline ───────────────────────
+    install_middleware(app, settings, modules, menu_registry, perm_registry)
+
+    # ── Phase 9: Routes, health, static files ──────────────
+    for mod in modules:
+        wire_module_routes(app, mod)
+
+    app.include_router(health_router)
+
+    static_dir = _PROJECT_ROOT / "host" / _STATIC_DIR_NAME
+    if static_dir.is_dir():
+        app.mount(_STATIC_MOUNT_PATH, StaticFiles(directory=static_dir), name=_STATIC_DIR_NAME)
+
+    mount_module_static_dirs(app, modules)
+
+    app.state.sm = Services(
+        settings=settings,
+        db=db_state,
+        event_bus=event_bus,
+        menu_registry=menu_registry,
+        permissions=perm_registry,
+        feature_flags=ff_registry,
+        health_registry=health_registry,
+        i18n_registry=i18n_registry,
+        inertia_config=inertia_config,
+        modules=tuple(modules),
+    )
+
+    return app

simple_module_hosting/bootstrap_settings.py

@@ -0,0 +1,55 @@
+"""Env-only settings read before the database is available.
+
+Everything here is needed either to connect to the DB, sign session cookies,
+or configure the Python process (logging, Vite asset URLs, module allowlist).
+These values stay in ``.env`` — all other settings live in the DB.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from simple_module_core.environments import NON_PROD_ENVIRONMENTS
+
+_PLACEHOLDER_SECRET_KEY = "change-me-in-production"
+
+
+class BootstrapSettings(BaseSettings):
+    """Pre-DB bootstrap environment knobs."""
+
+    model_config = SettingsConfigDict(env_prefix="SM_", env_file=".env", extra="ignore")
+
+    database_url: str = "sqlite+aiosqlite:///./app.db"
+    db_pool_size: int = 10
+    db_max_overflow: int = 20
+    db_pool_pre_ping: bool = True
+    db_pool_recycle: int = 1800
+
+    environment: str = "development"
+    secret_key: str = _PLACEHOLDER_SECRET_KEY
+    vite_dev_url: str = "http://localhost:5050"
+    debug: bool = False
+
+    log_level: str = "INFO"
+    log_format: Literal["json", "text"] = "json"
+
+    modules_enabled: list[str] | None = None
+
+    @property
+    def is_development(self) -> bool:
+        return self.environment == "development"
+
+    @model_validator(mode="after")
+    def _forbid_placeholder_secret_in_production(self) -> BootstrapSettings:
+        if (
+            self.environment not in NON_PROD_ENVIRONMENTS
+            and self.secret_key == _PLACEHOLDER_SECRET_KEY
+        ):
+            raise ValueError(
+                f"SM_SECRET_KEY must be set to a non-default value when "
+                f"SM_ENVIRONMENT={self.environment!r}. Generate one with "
+                "`python -c 'import secrets; print(secrets.token_urlsafe(48))'`."
+            )
+        return self

simple_module_hosting/cli.py

@@ -0,0 +1,292 @@
+"""SimpleModule CLI — `sm` console script.
+
+Currently exposes:
+
+* ``sm create-host <name>`` — scaffold a new host directory.
+* ``sm create-module <name>`` — scaffold a new module package.
+* ``sm gen-pages`` — regenerate the frontend pages manifest + Tailwind CSS.
+* ``sm sync-js-deps`` — install JS deps declared by installed modules.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+from simple_module_core import discover_modules
+
+from simple_module_hosting.scaffolding import (
+    _to_kebab_case,
+    collect_module_js_deps,
+    create_module,
+    repo_root_from_client_app,
+    write_module_pages_manifest,
+)
+from simple_module_hosting.scaffolding import (
+    create_host as _create_host,
+)
+
+
+@click.group()
+def main() -> None:
+    """SimpleModule developer CLI."""
+
+
+@main.command("new")
+@click.argument("name")
+@click.option(
+    "--dest",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Destination directory. Defaults to ./<name>.",
+)
+@click.option(
+    "--db",
+    type=click.Choice(["sqlite", "postgres"]),
+    default="sqlite",
+    show_default=True,
+    help="Database backend to configure in .env.example.",
+)
+@click.option(
+    "--tenancy/--no-tenancy",
+    default=False,
+    show_default=True,
+    help="Enable the multi-tenant middleware by default.",
+)
+@click.option(
+    "--yes",
+    "-y",
+    is_flag=True,
+    default=False,
+    help="Skip interactive prompts; accept all defaults.",
+)
+@click.option(
+    "--no-install",
+    is_flag=True,
+    default=False,
+    help="Skip 'uv sync' / 'npm install' / 'alembic upgrade head' after scaffolding.",
+)
+def new_project(
+    name: str,
+    dest: Path | None,
+    db: str,
+    tenancy: bool,
+    yes: bool,
+    no_install: bool,
+) -> None:
+    """Scaffold a new SimpleModule app — pre-wired with users, dashboard, permissions."""
+    target = dest or Path.cwd() / name
+    if not yes:
+        db = click.prompt(
+            "Database backend",
+            default=db,
+            type=click.Choice(["sqlite", "postgres"]),
+        )
+        tenancy = click.confirm("Enable multi-tenancy?", default=tenancy)
+
+    from simple_module_hosting.scaffolding import create_app_project
+
+    try:
+        create_app_project(target, name=name, db=db, tenancy=tenancy)
+    except FileExistsError as exc:
+        click.echo(f"ERROR: {exc}", err=True)
+        sys.exit(1)
+
+    click.echo(f"Created app '{name}' at {target}")
+    click.echo("\nPre-wired modules: users, dashboard, permissions")
+    click.echo("\nNext steps:")
+    click.echo(f"  cd {target}")
+    if no_install:
+        click.echo("  uv sync")
+        click.echo("  npm install")
+        click.echo("  alembic upgrade head")
+        click.echo("  make dev")
+        return
+
+    click.echo("Installing dependencies...")
+    for cmd in (["uv", "sync"], ["npm", "install"]):
+        result = subprocess.run(cmd, cwd=target, check=False)
+        if result.returncode != 0:
+            click.echo(
+                f"WARNING: {' '.join(cmd)} failed (exit {result.returncode}); "
+                f"finish setup manually.",
+                err=True,
+            )
+            return
+
+    subprocess.run(["uv", "run", "alembic", "upgrade", "head"], cwd=target, check=False)
+    click.echo("\nSetup complete. Run `make dev` in the new directory.")
+
+
+@main.command("create-host")
+@click.argument("name")
+@click.option(
+    "--dest",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Destination directory. Defaults to ./<name>.",
+)
+@click.option(
+    "--with",
+    "modules",
+    default="",
+    help="Comma-separated module names to declare as deps (e.g. --with=Auth,Products).",
+)
+def create_host(name: str, dest: Path | None, modules: str) -> None:
+    """Scaffold a new SimpleModule host project at ./<NAME>."""
+    target = dest or Path.cwd() / name
+    selected = [m.strip() for m in modules.split(",") if m.strip()]
+
+    try:
+        _create_host(target, name=name, modules=selected)
+    except FileExistsError as exc:
+        click.echo(f"ERROR: {exc}", err=True)
+        sys.exit(1)
+
+    click.echo(f"Created host '{name}' at {target}")
+    if selected:
+        click.echo(f"Declared modules: {', '.join(selected)}")
+    click.echo("\nNext steps:")
+    click.echo(f"  cd {target}")
+    click.echo("  uv sync")
+    click.echo("  cp .env.example .env")
+    click.echo('  alembic revision --autogenerate -m "initial schema"')
+    click.echo("  alembic upgrade head")
+    click.echo("  python main.py")
+
+
+@main.command("create-module")
+@click.argument("name")
+@click.option(
+    "--dest",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=None,
+    help="Destination directory. Defaults to ./simple_module_<package>.",
+)
+def create_module_cmd(name: str, dest: Path | None) -> None:
+    """Scaffold a publishable SimpleModule module package."""
+    slug = _to_kebab_case(name)
+    package = slug.replace("-", "_")
+    target = dest or Path.cwd() / f"simple_module_{package}"
+
+    try:
+        create_module(target, name=name)
+    except FileExistsError as exc:
+        click.echo(f"ERROR: {exc}", err=True)
+        sys.exit(1)
+
+    click.echo(f"Created module 'simple_module_{package}' at {target}")
+    click.echo("\nNext steps:")
+    click.echo(f"  cd {target}")
+    click.echo("  uv sync --extra dev")
+    click.echo("  uv run pytest")
+
+
+@main.command("gen-pages")
+@click.option(
+    "--host-dir",
+    type=click.Path(file_okay=False, exists=True, path_type=Path),
+    default=None,
+    help="Path to the host's client_app directory. Defaults to ./client_app.",
+)
+def gen_pages(host_dir: Path | None) -> None:
+    """Regenerate client_app/modules.{manifest.json,generated.ts,generated.css}."""
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+    output = host_dir or Path.cwd() / "client_app"
+    if not output.is_dir():
+        click.echo(f"ERROR: client_app directory not found at {output}", err=True)
+        sys.exit(1)
+
+    modules = discover_modules()
+    written = write_module_pages_manifest(modules, output)
+    click.echo(
+        f"Wrote {written['manifest'].name}, {written['generated'].name}, "
+        f"{written['css'].name} to {output}"
+    )
+
+
+@main.command("sync-js-deps")
+@click.option(
+    "--host-client-app",
+    type=click.Path(file_okay=False, exists=True, path_type=Path),
+    default=None,
+    help="Path to host/client_app. Defaults to ./client_app.",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Print the npm install command without running it.",
+)
+def sync_js_deps(host_client_app: Path | None, dry_run: bool) -> None:
+    """Install JS deps declared by installed modules into host's node_modules.
+
+    Walks every discovered module, reads its package.json, and runs a single
+    ``npm install --workspace host/client_app --save=false <specs>``. Use
+    this after ``pip install``-ing a module wheel that declares JS deps;
+    in-repo modules already flow through npm workspaces and need nothing.
+    """
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+
+    output = host_client_app or Path.cwd() / "client_app"
+    if not output.is_dir():
+        click.echo(f"ERROR: client_app directory not found at {output}", err=True)
+        sys.exit(1)
+
+    modules = discover_modules()
+    by_module = collect_module_js_deps(modules)
+    if not by_module:
+        click.echo("No module JS dependencies declared.")
+        return
+
+    # Flatten into a single spec list. npm's own resolver handles conflicts.
+    specs: list[str] = []
+    for mod_name in sorted(by_module):
+        for dep, rng in sorted(by_module[mod_name].items()):
+            specs.append(f"{dep}@{rng}")
+    # Dedupe while preserving first-seen order.
+    deduped: list[str] = []
+    seen: set[str] = set()
+    for spec in specs:
+        if spec not in seen:
+            seen.add(spec)
+            deduped.append(spec)
+
+    npm = shutil.which("npm")
+    if npm is None:
+        click.echo("ERROR: npm not found on PATH.", err=True)
+        sys.exit(1)
+
+    # Workspace path is relative to the repo root — derive it from output.
+    repo_root = repo_root_from_client_app(output)
+    try:
+        workspace = str(output.resolve().relative_to(repo_root))
+    except ValueError:
+        workspace = str(output.resolve())
+
+    cmd = [
+        npm,
+        "install",
+        "--workspace",
+        workspace,
+        "--save=false",
+        "--no-audit",
+        "--no-fund",
+        *deduped,
+    ]
+    click.echo("Installing module JS deps:")
+    for spec in deduped:
+        click.echo(f"  {spec}")
+    if dry_run:
+        click.echo("(dry-run) " + " ".join(cmd))
+        return
+    result = subprocess.run(cmd, cwd=repo_root, check=False)
+    sys.exit(result.returncode)
+
+
+if __name__ == "__main__":
+    main()