simple-module-cli 0.0.2__py3-none-any.whl

simple_module_cli/_env.py

@@ -0,0 +1,12 @@
+"""Shared helpers for editing dotenv-style files at scaffold time."""
+
+from __future__ import annotations
+
+__all__ = ["set_env_key"]
+
+
+def set_env_key(text: str, key: str, value: str) -> str:
+    """Replace or append ``KEY=VALUE`` in an env-style file body."""
+    lines = [ln for ln in text.splitlines() if not ln.startswith(f"{key}=")]
+    lines.append(f"{key}={value}")
+    return "\n".join(lines) + "\n"

simple_module_cli/app_project.py

@@ -0,0 +1,123 @@
+"""Greenfield ``simple-module new`` scaffolding.
+
+Wraps :func:`simple_module_hosting.scaffolding.create_host` with the
+opinionated bits — module-list resolution from the CLI catalog, secret
+generation, DB URL selection, ``pyproject.toml`` / ``package.json``
+rewriting, and post-scaffold recipe application.
+
+Lives in its own module to keep ``scaffolding.py`` under the per-file
+line cap and to make the surface area of "host scaffold" vs "app
+scaffold" obvious to readers.
+"""
+
+from __future__ import annotations
+
+import json as _json
+import secrets as _secrets
+from collections.abc import Sequence
+from pathlib import Path
+
+from simple_module_cli._env import set_env_key
+from simple_module_cli.case import to_kebab_case, to_pascal_case
+from simple_module_cli.catalog import CATALOG, PRESETS, expand_deps
+from simple_module_cli.recipes import RECIPES, ScaffoldCtx
+from simple_module_cli.scaffolding import create_host
+
+__all__ = ["create_app_project"]
+
+_FRAMEWORK_VERSION = "0.0.1"
+
+_APP_PY_DEV_DEPS = [f"simple_module_test=={_FRAMEWORK_VERSION}", "pytest>=8.0"]
+
+_APP_NPM_DEPS = {
+    "@simple-module-py/ui": _FRAMEWORK_VERSION,
+    "@simple-module-py/i18n": _FRAMEWORK_VERSION,
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^1.0.0",
+}
+_APP_NPM_DEV_DEPS = {
+    "@simple-module-py/tsconfig": _FRAMEWORK_VERSION,
+    "@vitejs/plugin-react": "^5.0.0",
+    "typescript": "^5.6.0",
+    "vite": "^8.0.0",
+}
+
+
+def create_app_project(
+    target: Path,
+    *,
+    name: str,
+    db: str = "sqlite",
+    tenancy: bool = False,
+    selected: Sequence[str] | None = None,
+) -> None:
+    """Greenfield ``simple-module new`` scaffold.
+
+    Wraps :func:`create_host` with a chosen module list (defaults to the
+    ``standard`` preset), generates a secret, picks a DB URL, rewrites
+    the generated ``package.json`` / ``pyproject.toml`` to pin exact
+    framework versions, and applies any matching post-scaffold recipes
+    (e.g. the ``background_tasks`` recipe drops a Celery worker stack).
+    """
+    if target.exists() and any(target.iterdir()):
+        raise FileExistsError(
+            f"Destination {target} already exists and is non-empty; "
+            "choose a new path or remove its contents first."
+        )
+
+    chosen = list(selected) if selected is not None else list(PRESETS["standard"])
+    resolved, _added = expand_deps(chosen)
+
+    display_names = [to_pascal_case(CATALOG[m].display) for m in resolved]
+    create_host(target, name=name, modules=display_names)
+
+    py_deps = [f"simple_module_hosting=={_FRAMEWORK_VERSION}"] + [
+        f"{CATALOG[m].package}=={_FRAMEWORK_VERSION}" for m in resolved
+    ]
+
+    env_path = target / ".env.example"
+    env_text = env_path.read_text(encoding="utf-8") if env_path.exists() else ""
+    env_text = set_env_key(env_text, "SM_SECRET_KEY", _secrets.token_urlsafe(32))
+    env_text = set_env_key(env_text, "SM_DATABASE_URL", _db_url(db, to_kebab_case(name)))
+    env_text = set_env_key(env_text, "SM_MULTI_TENANT", "true" if tenancy else "false")
+    env_path.write_text(env_text, encoding="utf-8")
+
+    pyproject = target / "pyproject.toml"
+    if pyproject.exists():
+        text = pyproject.read_text(encoding="utf-8")
+        text = _inject_py_deps(text, py_deps, _APP_PY_DEV_DEPS)
+        pyproject.write_text(text, encoding="utf-8")
+
+    pkg_path = target / "package.json"
+    if pkg_path.exists():
+        data = _json.loads(pkg_path.read_text(encoding="utf-8"))
+    else:
+        data = {"name": to_kebab_case(name), "private": True, "type": "module"}
+    data.setdefault("dependencies", {}).update(_APP_NPM_DEPS)
+    data.setdefault("devDependencies", {}).update(_APP_NPM_DEV_DEPS)
+    pkg_path.write_text(_json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+    ctx = ScaffoldCtx(name=name, db=db, tenancy=tenancy, selected=tuple(resolved))
+    for mod_name in resolved:
+        recipe_key = CATALOG[mod_name].recipe
+        if recipe_key is not None and recipe_key in RECIPES:
+            RECIPES[recipe_key].apply(target, ctx)
+
+
+def _db_url(db: str, slug: str) -> str:
+    if db == "postgres":
+        return f"postgresql+asyncpg://postgres:postgres@localhost:5432/{slug}"
+    return "sqlite+aiosqlite:///./app.db"
+
+
+def _inject_py_deps(text: str, deps: list[str], dev_deps: list[str]) -> str:
+    """Replace project.dependencies + dependency-groups.dev in a pyproject.toml."""
+    import tomlkit
+
+    doc = tomlkit.parse(text)
+    project = doc.setdefault("project", tomlkit.table())
+    project["dependencies"] = list(deps)
+    groups = doc.setdefault("dependency-groups", tomlkit.table())
+    groups["dev"] = list(dev_deps)
+    return tomlkit.dumps(doc)

simple_module_cli/case.py

@@ -0,0 +1,30 @@
+"""Identifier case-conversion helpers used by every scaffolder.
+
+Module/host names are accepted in any case style and normalized to the
+three forms the templates need: snake_case (Python package + entry-point
+key), kebab-case (PyPI slug), and PascalCase (display name in Meta).
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = ["to_kebab_case", "to_pascal_case", "to_snake_case"]
+
+
+def to_snake_case(name: str) -> str:
+    """'MyFeature' / 'my-feature' / 'My Feature' -> 'my_feature'."""
+    s = re.sub(r"(?<!^)(?=[A-Z])", "_", name)
+    s = re.sub(r"[\s\-]+", "_", s)
+    return s.lower()
+
+
+def to_kebab_case(name: str) -> str:
+    """'MyFeature' / 'my_feature' -> 'my-feature' (used as the PyPI slug)."""
+    return to_snake_case(name).replace("_", "-")
+
+
+def to_pascal_case(name: str) -> str:
+    """'my-feature' / 'my_feature' -> 'MyFeature' (the display name in Meta)."""
+    snake = to_snake_case(name)
+    return "".join(part.capitalize() for part in snake.split("_") if part)

simple_module_cli/catalog.py

@@ -0,0 +1,107 @@
+"""Hardcoded catalog of installable SimpleModule modules.
+
+Each :class:`ModuleEntry` declares the PyPI package name, a human display
+name, transitive ``requires`` (other catalog keys), and an optional
+``recipe`` key for post-scaffold actions handled by :mod:`.recipes`.
+
+:func:`expand_deps` takes a user-selected subset and returns a
+topologically ordered superset including every transitive requirement,
+plus the list of ``(added, required_by)`` pairs for printing back to the
+user.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+__all__ = ["CATALOG", "PRESETS", "ModuleEntry", "expand_deps"]
+
+
+@dataclass(frozen=True)
+class ModuleEntry:
+    name: str
+    package: str
+    display: str
+    requires: tuple[str, ...] = field(default_factory=tuple)
+    recipe: str | None = None
+
+
+CATALOG: dict[str, ModuleEntry] = {
+    "auth": ModuleEntry("auth", "simple_module_auth", "Auth"),
+    "users": ModuleEntry("users", "simple_module_users", "Users", requires=("auth",)),
+    "permissions": ModuleEntry(
+        "permissions",
+        "simple_module_permissions",
+        "Permissions",
+        requires=("auth", "users"),
+    ),
+    "products": ModuleEntry("products", "simple_module_products", "Products"),
+    "dashboard": ModuleEntry(
+        "dashboard",
+        "simple_module_dashboard",
+        "Dashboard",
+        requires=("users", "products"),
+    ),
+    "settings": ModuleEntry("settings", "simple_module_settings", "Settings"),
+    "feature_flags": ModuleEntry("feature_flags", "simple_module_feature_flags", "Feature Flags"),
+    "file_storage": ModuleEntry(
+        "file_storage",
+        "simple_module_file_storage",
+        "File Storage",
+        requires=("settings",),
+    ),
+    "background_tasks": ModuleEntry(
+        "background_tasks",
+        "simple_module_background_tasks",
+        "Background Tasks",
+        requires=("users",),
+        recipe="background_tasks",
+    ),
+    "datasets": ModuleEntry(
+        "datasets",
+        "simple_module_datasets",
+        "Datasets",
+        requires=("file_storage", "background_tasks"),
+    ),
+}
+
+
+PRESETS: dict[str, tuple[str, ...]] = {
+    "minimal": ("users",),
+    "standard": ("users", "dashboard", "permissions"),
+    "full": tuple(CATALOG),
+}
+
+
+def expand_deps(selected: Iterable[str]) -> tuple[list[str], list[tuple[str, str]]]:
+    """Return ``(topo-ordered resolved list, [(added, required_by), ...])``.
+
+    Raises :class:`KeyError` if any input name is missing from the
+    catalog. The error message lists the available catalog keys so a
+    user typo (`--with=does_not_exist`) is self-correcting.
+    """
+    selected_list = list(selected)
+    for name in selected_list:
+        if name not in CATALOG:
+            available = ", ".join(sorted(CATALOG))
+            raise KeyError(f"unknown module: {name!r}; available: {available}")
+
+    explicit = set(selected_list)
+    resolved: list[str] = []
+    in_resolved: set[str] = set()
+    added: list[tuple[str, str]] = []
+
+    def _visit(name: str, required_by: str | None) -> None:
+        if name in in_resolved:
+            return
+        for dep in CATALOG[name].requires:
+            _visit(dep, required_by=name)
+        resolved.append(name)
+        in_resolved.add(name)
+        if required_by is not None and name not in explicit:
+            added.append((name, required_by))
+
+    for name in selected_list:
+        _visit(name, required_by=None)
+    return resolved, added

simple_module_cli/cli.py

@@ -0,0 +1,104 @@
+"""Root `sm` Typer app — scaffolders + plugin mount.
+
+Built-in commands:
+  sm new
+  sm create-host
+  sm create-module
+
+Plugins discovered via the ``simple_module_cli.cli_plugins`` entry-point
+group are mounted as named subgroups (e.g. ``sm host gen-pages``).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from simple_module_cli.case import to_kebab_case
+from simple_module_cli.new import new_project
+from simple_module_cli.plugins import discover_and_mount
+from simple_module_cli.scaffolding import create_host as _create_host
+from simple_module_cli.scaffolding import create_module as _create_module
+
+app = typer.Typer(
+    help="SimpleModule developer CLI.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+app.command("new")(new_project)
+
+
+@app.command("create-host")
+def create_host(
+    name: Annotated[str, typer.Argument(help="Host project name.")],
+    dest: Annotated[
+        Path | None,
+        typer.Option("--dest", help="Destination directory. Defaults to ./<name>."),
+    ] = None,
+    modules: Annotated[
+        str,
+        typer.Option(
+            "--with",
+            help="Comma-separated module names to declare as deps (e.g. Auth,Products).",
+        ),
+    ] = "",
+) -> 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:
+        typer.echo(f"ERROR: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+    typer.echo(f"Created host '{name}' at {target}")
+    if selected:
+        typer.echo(f"Declared modules: {', '.join(selected)}")
+    typer.echo("\nNext steps:")
+    typer.echo(f"  cd {target}")
+    typer.echo("  uv sync")
+    typer.echo("  cp .env.example .env")
+    typer.echo('  alembic revision --autogenerate -m "initial schema"')
+    typer.echo("  alembic upgrade head")
+    typer.echo("  python main.py")
+
+
+@app.command("create-module")
+def create_module(
+    name: Annotated[str, typer.Argument(help="Module name (any case).")],
+    dest: Annotated[
+        Path | None,
+        typer.Option("--dest", help="Destination dir. Defaults to ./simple_module_<name>."),
+    ] = 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:
+        typer.echo(f"ERROR: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+    typer.echo(f"Created module 'simple_module_{package}' at {target}")
+    typer.echo("\nNext steps:")
+    typer.echo(f"  cd {target}")
+    typer.echo("  uv sync --extra dev")
+    typer.echo("  uv run pytest")
+
+
+discover_and_mount(app)
+
+
+def main() -> None:
+    """Entry point for the `sm` console script."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

simple_module_cli/new.py

@@ -0,0 +1,124 @@
+"""``sm new`` Typer command — flag-driven or interactive scaffolder."""
+
+from __future__ import annotations
+
+import subprocess
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from simple_module_cli.app_project import create_app_project
+from simple_module_cli.catalog import PRESETS, expand_deps
+from simple_module_cli.wizard import run_wizard
+
+__all__ = ["new_project"]
+
+
+class Db(StrEnum):
+    sqlite = "sqlite"
+    postgres = "postgres"
+
+
+class Preset(StrEnum):
+    minimal = "minimal"
+    standard = "standard"
+    full = "full"
+
+
+def new_project(
+    name: Annotated[str, typer.Argument(help="App name (used for directory + package).")],
+    dest: Annotated[
+        Path | None,
+        typer.Option("--dest", help="Destination directory. Defaults to ./<name>."),
+    ] = None,
+    db: Annotated[
+        Db,
+        typer.Option("--db", help="Database backend to configure in .env.example."),
+    ] = Db.sqlite,
+    tenancy: Annotated[
+        bool,
+        typer.Option("--tenancy/--no-tenancy", help="Enable the multi-tenant middleware."),
+    ] = False,
+    preset: Annotated[
+        Preset | None,
+        typer.Option("--preset", help="Module preset. Combine with --with."),
+    ] = None,
+    extra: Annotated[
+        str,
+        typer.Option(
+            "--with",
+            help="Comma-separated extra modules (e.g. background_tasks,file_storage).",
+        ),
+    ] = "",
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Skip interactive prompts; accept defaults."),
+    ] = False,
+    no_install: Annotated[
+        bool,
+        typer.Option(
+            "--no-install",
+            help="Skip 'uv sync' / 'npm install' / 'alembic upgrade head' after scaffolding.",
+        ),
+    ] = False,
+) -> None:
+    """Scaffold a new SimpleModule app, optionally with background jobs."""
+    target = dest or Path.cwd() / name
+    extra_list = [m.strip() for m in extra.split(",") if m.strip()]
+    flag_driven = preset is not None or bool(extra_list)
+
+    if yes or flag_driven:
+        chosen = list(PRESETS[(preset or Preset.standard).value]) + extra_list
+        try:
+            resolved, added = expand_deps(chosen)
+        except KeyError as exc:
+            typer.echo(f"ERROR: {exc}", err=True)
+            raise typer.Exit(code=1) from exc
+        for added_name, required_by in added:
+            typer.echo(f"Added {added_name} (required by {required_by})")
+        db_final, tenancy_final = db.value, tenancy
+    else:
+        try:
+            db_final, tenancy_final, resolved = run_wizard(
+                default_db=db.value, default_tenancy=tenancy
+            )
+        except typer.Abort:
+            typer.echo("Aborted.", err=True)
+            raise typer.Exit(code=1) from None
+
+    try:
+        create_app_project(target, name=name, db=db_final, tenancy=tenancy_final, selected=resolved)
+    except FileExistsError as exc:
+        typer.echo(f"ERROR: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+    typer.echo(f"Created app '{name}' at {target}")
+    typer.echo(f"Modules: {', '.join(resolved)}")
+    typer.echo("\nNext steps:")
+    typer.echo(f"  cd {target}")
+    if no_install:
+        typer.echo("  uv sync")
+        typer.echo("  npm install")
+        typer.echo("  alembic upgrade head")
+        typer.echo("  make dev")
+        if "background_tasks" in resolved:
+            typer.echo("  docker compose up -d redis worker beat   # background jobs")
+        return
+
+    typer.echo("Installing dependencies...")
+    for cmd in (["uv", "sync"], ["npm", "install"]):
+        result = subprocess.run(cmd, cwd=target, check=False)
+        if result.returncode != 0:
+            typer.echo(
+                f"WARNING: {' '.join(cmd)} failed (exit {result.returncode}); "
+                "finish setup manually.",
+                err=True,
+            )
+            return
+
+    subprocess.run(["uv", "run", "alembic", "upgrade", "head"], cwd=target, check=False)
+    typer.echo("\nSetup complete. Run `make dev` in the new directory.")
+    if "background_tasks" in resolved:
+        typer.echo("For background jobs, also run: docker compose up -d redis worker beat")

simple_module_cli/plugins.py

@@ -0,0 +1,56 @@
+"""Plugin discovery for ``sm`` via the ``simple_module_cli.cli_plugins`` group.
+
+Each entry-point's value (``module:attr``) must resolve to a
+:class:`typer.Typer` instance. The entry-point name becomes the
+subcommand namespace under ``sm`` (e.g. ``sm host gen-pages``).
+
+Failed loads (broken import, wrong type) print one line to stderr and
+are skipped — ``sm`` keeps working with whatever else loads.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterator
+from importlib.metadata import EntryPoint, entry_points
+
+import typer
+
+__all__ = ["discover_and_mount"]
+
+_GROUP = "simple_module_cli.cli_plugins"
+
+
+def _iter_plugin_entries() -> Iterator[EntryPoint]:
+    """Indirection point for tests to inject fake entry points."""
+    yield from entry_points(group=_GROUP)
+
+
+def discover_and_mount(root: typer.Typer) -> None:
+    """Mount every installed plugin under its entry-point name."""
+    seen: set[str] = set()
+    for entry in _iter_plugin_entries():
+        if entry.name in seen:
+            print(
+                f"[simple-module] duplicate plugin subgroup '{entry.name}' "
+                f"from {entry.value!r}; keeping first registration.",
+                file=sys.stderr,
+            )
+            continue
+        try:
+            plugin_app = entry.load()
+        except Exception as exc:
+            print(
+                f"[simple-module] failed to load plugin '{entry.name}' ({entry.value}): {exc}",
+                file=sys.stderr,
+            )
+            continue
+        if not isinstance(plugin_app, typer.Typer):
+            print(
+                f"[simple-module] plugin '{entry.name}' did not export a "
+                f"typer.Typer instance (got {type(plugin_app).__name__}); skipping.",
+                file=sys.stderr,
+            )
+            continue
+        root.add_typer(plugin_app, name=entry.name)
+        seen.add(entry.name)

simple_module_cli/recipes.py

@@ -0,0 +1,93 @@
+"""Per-module post-scaffold recipes.
+
+A recipe is invoked by ``sm new`` after the base host scaffold lands. It
+performs module-specific actions (write helper scripts, append Make
+targets, drop a docker-compose stack). The framework layer is kept free
+of devex concerns — recipes know about Makefiles and compose, framework
+scaffolding does not.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import shutil
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from simple_module_cli._env import set_env_key
+
+__all__ = [
+    "RECIPES",
+    "BackgroundTasksRecipe",
+    "Recipe",
+    "ScaffoldCtx",
+]
+
+_BG_BROKER_ENV_KEY = "SM_BG_TASKS_BROKER_URL"
+_BG_BROKER_DEFAULT = "redis://redis:6379/0"
+_MAKEFILE_MARKER = "# --- background_tasks --"
+
+
+@dataclass(frozen=True)
+class ScaffoldCtx:
+    name: str
+    db: str
+    tenancy: bool
+    selected: Sequence[str]
+
+
+class Recipe(Protocol):
+    def apply(self, target: Path, ctx: ScaffoldCtx) -> None: ...
+
+
+def _optional_template_root(name: str) -> Path:
+    """Resolve ``templates/host/_optional/<name>/`` from package data."""
+    base = importlib.resources.files("simple_module_cli")
+    return Path(str(base / "templates" / "host" / "_optional" / name))
+
+
+class BackgroundTasksRecipe:
+    """Lays down run_worker.py + compose + Dockerfile + Make targets."""
+
+    def apply(self, target: Path, ctx: ScaffoldCtx) -> None:
+        templates = _optional_template_root("background_tasks")
+
+        run_worker_dest = target / "scripts" / "run_worker.py"
+        compose_dest = target / "docker-compose.yml"
+        dockerfile_dest = target / "docker" / "worker.Dockerfile"
+
+        for path in (run_worker_dest, compose_dest, dockerfile_dest):
+            if path.exists():
+                raise FileExistsError(
+                    f"{path} already exists — refusing to clobber. "
+                    "Remove the file or run `sm new` against an empty directory."
+                )
+
+        run_worker_dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(templates / "run_worker.py", run_worker_dest)
+
+        shutil.copy2(templates / "docker-compose.yml", compose_dest)
+
+        dockerfile_dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(templates / "worker.Dockerfile", dockerfile_dest)
+
+        env_path = target / ".env.example"
+        env_text = env_path.read_text(encoding="utf-8") if env_path.exists() else ""
+        env_path.write_text(
+            set_env_key(env_text, _BG_BROKER_ENV_KEY, _BG_BROKER_DEFAULT),
+            encoding="utf-8",
+        )
+
+        makefile_path = target / "Makefile"
+        snippet = (templates / "Makefile.snippet").read_text(encoding="utf-8")
+        existing = makefile_path.read_text(encoding="utf-8") if makefile_path.exists() else ""
+        if _MAKEFILE_MARKER not in existing:
+            sep = "" if existing.endswith("\n") or not existing else "\n"
+            makefile_path.write_text(existing + sep + snippet, encoding="utf-8")
+
+
+RECIPES: dict[str, Recipe] = {
+    "background_tasks": BackgroundTasksRecipe(),
+}