simple-module-cli 0.0.12__tar.gz → 0.0.13__tar.gz

{simple_module_cli-0.0.12 → simple_module_cli-0.0.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_cli
-Version: 0.0.12
+Version: 0.0.13
 Summary: Standalone scaffolder for the SimpleModule framework — `smpy new`, `smpy create-module`, plugin host.
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python

{simple_module_cli-0.0.12 → simple_module_cli-0.0.13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_cli"
-version = "0.0.12"
+version = "0.0.13"
 description = "Standalone scaffolder for the SimpleModule framework — `smpy new`, `smpy create-module`, plugin host."
 readme = "README.md"
 license = "MIT"

{simple_module_cli-0.0.12 → simple_module_cli-0.0.13}/simple_module_cli/app_project.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 
 import json as _json
 import secrets as _secrets
+import shutil as _shutil
 from collections.abc import Sequence
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _pkg_version
@@ -26,6 +27,7 @@ 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 (
+    SAFE_PRESERVED_NAMES,
     _module_to_pypi_name,
     create_host,
     create_module,
@@ -55,7 +57,14 @@ def _resolve_framework_version() -> str:
 
 _FRAMEWORK_VERSION = _resolve_framework_version()
 
-_APP_PY_DEV_DEPS = [f"simple_module_test=={_FRAMEWORK_VERSION}", "pytest>=8.0"]
+# Pin ``simple_module_cli`` as a dev dep so ``uv run smpy`` resolves to the
+# project venv. The global ``uv tool`` install runs in its own isolated venv
+# that can't see the project's plugin entry points (issue #134).
+_APP_PY_DEV_DEPS = [
+    f"simple_module_test=={_FRAMEWORK_VERSION}",
+    f"simple_module_cli=={_FRAMEWORK_VERSION}",
+    "pytest>=8.0",
+]
 
 _APP_NPM_DEPS = {
     "@simple-module-py/ui": _FRAMEWORK_VERSION,
@@ -89,35 +98,39 @@ def create_app_project(
     tenancy: bool = False,
     selected: Sequence[str] | None = None,
     flat: bool = False,
-) -> None:
+) -> tuple[Path, list[Path]]:
     """Greenfield ``simple-module new`` scaffold.
 
-    In workspace mode (the default), lays down a uv + npm workspace at
-    ``target/`` with the host under ``target/host/`` and a sample module
-    under ``target/modules/hello/``. In flat mode (``flat=True``), keeps
-    the legacy single-host layout: host files at ``target/`` with no
-    ``modules/`` directory or workspace plumbing.
+    Workspace mode (default) lays down a uv + npm workspace at ``target/``
+    with the host under ``target/host/`` and a sample module under
+    ``target/modules/hello/``. Flat mode keeps the legacy single-host layout.
+    Tolerates ``SAFE_PRESERVED_NAMES`` at ``target`` (leftovers from
+    ``git init`` / ``gh repo create`` / IDE setup); other pre-existing
+    entries raise ``FileExistsError``.
 
-    Generates a secret, picks a DB URL, rewrites the host's
-    ``pyproject.toml`` / the relevant ``package.json`` to pin exact
-    framework versions, and applies any matching post-scaffold recipes
-    (e.g. the ``background_tasks`` recipe drops a Celery worker stack).
+    Returns ``(host_dir, preserved)`` — the host directory (``target`` in
+    flat mode, ``target/host`` in workspace mode) and the paths whose
+    scaffold copy was skipped because the user already had one.
     """
-    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]
     host_dir = target if flat else target / "host"
+    preserved: list[Path] = []
     if not flat:
-        target.mkdir(parents=True, exist_ok=True)
-        create_workspace(target, name=name)
-    create_host(host_dir, name=name, modules=display_names, framework_version=_FRAMEWORK_VERSION)
+        preserved.extend(
+            create_workspace(target, name=name, preserve_existing=SAFE_PRESERVED_NAMES)
+        )
+    preserved.extend(
+        create_host(
+            host_dir,
+            name=name,
+            modules=display_names,
+            framework_version=_FRAMEWORK_VERSION,
+            preserve_existing=SAFE_PRESERVED_NAMES if flat else frozenset(),
+        )
+    )
     if not flat:
         _strip_workspace_owned_files(host_dir)
 
@@ -169,6 +182,8 @@ def create_app_project(
         if recipe_key is not None and recipe_key in RECIPES:
             RECIPES[recipe_key].apply(target, ctx)
 
+    return host_dir, preserved
+
 
 def _strip_workspace_owned_files(host_dir: Path) -> None:
     """Drop host copies of files the workspace root owns in workspace mode."""
@@ -181,6 +196,9 @@ def _scaffold_sample_module(target: Path) -> None:
     if sample_dest.exists():
         return
     create_module(sample_dest, name=_SAMPLE_MODULE_NAME)
+    # GitHub only reads workflows from the repo root, so the template's
+    # .github/ is dead inside a workspace.
+    _shutil.rmtree(sample_dest / ".github")
     _pin_sample_module_deps(sample_dest)
     _seed_static_dist_placeholder(sample_dest / _SAMPLE_MODULE_NAME / "static" / "dist")
 

simple_module_cli-0.0.13/simple_module_cli/case.py

@@ -0,0 +1,79 @@
+"""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__ = [
+    "InvalidScaffoldNameError",
+    "to_kebab_case",
+    "to_pascal_case",
+    "to_snake_case",
+    "validate_scaffold_name",
+]
+
+
+class InvalidScaffoldNameError(ValueError):
+    """Raised when a user-supplied scaffold name can't be canonicalized.
+
+    Names that mix case, lead with a digit, contain spaces or non
+    ``[a-z0-9_-]`` characters, or mix ``_`` and ``-`` separators within
+    the same identifier are ambiguous: the scaffolder would have to guess
+    a canonical form, and the directory name would diverge from the
+    READMEs that reference it. Reject up front instead.
+    """
+
+
+def to_snake_case(name: str) -> str:
+    """'MyFeature' / 'my-feature' / 'My Feature' / 'URLPath' -> 'my_feature' / 'url_path'.
+
+    Handles acronyms by treating ``Acronym|Word`` and ``word|Capital`` as
+    boundaries: ``URLPath`` -> ``url_path``, ``APIClient`` -> ``api_client``,
+    ``HTTPServer2`` -> ``http_server2``. The single-pass ``(?=[A-Z])`` form
+    that preceded this would emit ``u_r_l_path`` and propagate the typo
+    into the PyPI slug + display name.
+    """
+    s = re.sub(r"[\s\-]+", "_", name)
+    s = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", s)
+    s = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", 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)
+
+
+_VALID_NAME_RE = re.compile(r"^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$")
+
+
+def validate_scaffold_name(name: str) -> str:
+    """Reject ambiguous host/module names; return the canonical display form.
+
+    A valid name is lowercase alphanumerics with at most one separator
+    style — either ``_`` or ``-``, not both. Examples:
+
+    * ``simple_module_chat`` -> ``simple_module_chat``
+    * ``simple-module-chat`` -> ``simple-module-chat``
+    * ``MyApp`` -> rejected (mixed case is ambiguous: ``my-app`` or ``my_app``?)
+    * ``1chat`` -> rejected (must start with a letter)
+    * ``foo_bar-baz`` -> rejected (mixed separators leave no canonical form)
+    """
+    if not name or not _VALID_NAME_RE.match(name) or ("_" in name and "-" in name):
+        raise InvalidScaffoldNameError(
+            f"{name!r} is not a valid scaffold name. Use lowercase letters and "
+            "digits with at most one separator style (all '_' or all '-'), "
+            "starting with a letter. e.g. 'my_app', 'my-app', or 'myapp'."
+        )
+    return name

{simple_module_cli-0.0.12 → simple_module_cli-0.0.13}/simple_module_cli/new.py

@@ -11,11 +11,14 @@ from typing import Annotated
 import typer
 
 from simple_module_cli.app_project import create_app_project
+from simple_module_cli.case import InvalidScaffoldNameError, to_kebab_case, validate_scaffold_name
 from simple_module_cli.catalog import PRESETS, expand_deps
 from simple_module_cli.wizard import run_wizard
 
 __all__ = ["new_project"]
 
+_ALEMBIC = ("uv", "run", "alembic")
+
 
 class Db(StrEnum):
     sqlite = "sqlite"
@@ -61,7 +64,7 @@ def new_project(
         bool,
         typer.Option(
             "--no-install",
-            help="Skip 'uv sync' / 'npm install' / 'alembic upgrade head' after scaffolding.",
+            help=("Skip 'uv sync' / 'npm install' / initial alembic migration after scaffolding."),
         ),
     ] = False,
     flat: Annotated[
@@ -76,6 +79,14 @@ def new_project(
     ] = False,
 ) -> None:
     """Scaffold a new SimpleModule app, optionally with background jobs."""
+    try:
+        validate_scaffold_name(name)
+    except InvalidScaffoldNameError as exc:
+        typer.echo(f"ERROR: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    pypi_name = to_kebab_case(name)
+    if pypi_name != name:
+        typer.echo(f"Normalizing PyPI name to {pypi_name!r}.")
     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)
@@ -100,7 +111,7 @@ def new_project(
             raise typer.Exit(code=1) from None
 
     try:
-        create_app_project(
+        host_dir, preserved = create_app_project(
             target,
             name=name,
             db=db_final,
@@ -114,12 +125,21 @@ def new_project(
 
     typer.echo(f"Created app '{name}' at {target}")
     typer.echo(f"Modules: {', '.join(resolved)}")
+    if preserved:
+        typer.echo(
+            "\nPreserved existing files (scaffold's versions were skipped — "
+            "merge by hand if you want their contents):"
+        )
+        for path in preserved:
+            rel = path.relative_to(target) if path.is_relative_to(target) else path
+            typer.echo(f"  {rel}")
     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 migration msg="initial schema"')
+        typer.echo("  make migrate")
         typer.echo("  make dev")
         if "background_tasks" in resolved:
             typer.echo("  docker compose up -d redis worker beat   # background jobs")
@@ -143,7 +163,24 @@ def new_project(
             )
             return
 
-    subprocess.run(["uv", "run", "alembic", "upgrade", "head"], cwd=target, check=False)
+    _bootstrap_initial_migration(host_dir)
+    subprocess.run([*_ALEMBIC, "upgrade", "head"], cwd=host_dir, 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")
+
+
+def _bootstrap_initial_migration(host_dir: Path) -> None:
+    """Autogenerate the baseline migration if the scaffold ships none.
+
+    Without a real revision, ``alembic upgrade head`` is a silent no-op
+    against an empty schema — the bundled modules' tables never exist.
+    """
+    versions_dir = host_dir / "migrations" / "versions"
+    if any(p.name != "__init__.py" for p in versions_dir.glob("*.py")):
+        return
+    subprocess.run(
+        [*_ALEMBIC, "revision", "--autogenerate", "-m", "initial schema"],
+        cwd=host_dir,
+        check=False,
+    )

{simple_module_cli-0.0.12 → simple_module_cli-0.0.13}/simple_module_cli/scaffolding.py

@@ -21,15 +21,35 @@ import shutil
 from collections.abc import Mapping, Sequence
 from pathlib import Path
 
-from simple_module_cli.case import to_kebab_case, to_pascal_case, to_snake_case
-
-__all__ = ["create_host", "create_module", "create_workspace"]
+from simple_module_cli.case import (
+    to_kebab_case,
+    to_pascal_case,
+    to_snake_case,
+    validate_scaffold_name,
+)
+
+__all__ = [
+    "SAFE_PRESERVED_NAMES",
+    "create_host",
+    "create_module",
+    "create_workspace",
+]
 
 logger = logging.getLogger(__name__)
 
 _TEMPLATES_PACKAGE = "simple_module_cli.templates"
 _PACKAGE_PATH_TOKEN = "__PACKAGE__"
 
+# Pre-existing entries we tolerate at a scaffold target — typical leftovers
+# from ``git init`` / ``gh repo create`` / IDE setup.
+SAFE_PRESERVED_NAMES = frozenset(
+    {".git", ".gitignore", ".gitattributes", ".editorconfig", ".DS_Store"}
+    | {".claude", ".vscode", ".idea"}
+    | {"README", "README.md", "README.rst"}
+    | {"LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING"}
+    | {"CHANGELOG.md", "CONTRIBUTING.md", "CODE_OF_CONDUCT.md"}
+)
+
 
 def _module_to_pypi_name(name: str) -> str:
     return f"simple_module_{name.lower()}"
@@ -45,12 +65,21 @@ def _iter_template_files(template_root: Path):
         yield path
 
 
-def _require_empty_dest(dest: Path) -> None:
-    if dest.exists() and any(dest.iterdir()):
-        raise FileExistsError(
-            f"Destination {dest} already exists and is non-empty. "
-            "Choose a new path or remove the contents first."
-        )
+def _require_empty_dest(dest: Path, *, preserve_existing: frozenset[str] = frozenset()) -> None:
+    """Refuse a non-empty destination unless every top-level entry is allowed.
+
+    ``preserve_existing`` is matched against the *name* of each top-level entry,
+    so callers can permit common pre-existing files (``.git``, ``README.md``,
+    ...) without silently overwriting unrelated user content.
+    """
+    if dest.exists():
+        unexpected = sorted(p.name for p in dest.iterdir() if p.name not in preserve_existing)
+        if unexpected:
+            raise FileExistsError(
+                f"Destination {dest} exists and contains files that would collide "
+                f"with the scaffold: {', '.join(unexpected)}. "
+                "Move them aside or choose another path."
+            )
     dest.mkdir(parents=True, exist_ok=True)
 
 
@@ -66,13 +95,20 @@ def _apply_template_files(
     substitutions: Mapping[str, str],
     *,
     path_rewrites: Mapping[str, str] | None = None,
-) -> None:
+    preserve_existing: frozenset[str] = frozenset(),
+) -> list[Path]:
+    """Write template files into ``dest``; return paths skipped to preserve the user's copy."""
+    preserved: list[Path] = []
     for src in _iter_template_files(src_root):
         rel_str = str(src.relative_to(src_root))
         for old, new in (path_rewrites or {}).items():
             rel_str = rel_str.replace(old, new)
         rel_str = rel_str.removesuffix(".tpl")
         target = dest / rel_str
+        top = Path(rel_str).parts[0] if rel_str else ""
+        if top in preserve_existing and target.exists():
+            preserved.append(target)
+            continue
         target.parent.mkdir(parents=True, exist_ok=True)
         if src.suffix == ".tpl":
             text = src.read_text(encoding="utf-8")
@@ -81,29 +117,41 @@ def _apply_template_files(
             target.write_text(text, encoding="utf-8")
         else:
             shutil.copy2(src, target)
+    return preserved
 
 
 def create_workspace(
     dest: Path,
     name: str,
     template_root: Path | None = None,
-) -> Path:
-    """Materialize the workspace-root shell at ``dest``.
+    *,
+    preserve_existing: frozenset[str] = frozenset(),
+) -> list[Path]:
+    """Materialize the workspace-root shell at ``dest``; return preserved paths.
 
     Lays down the top-level ``pyproject.toml`` (uv workspace), ``package.json``
     (npm workspace), ``Makefile`` (delegates to host), ``.env.example``,
     ``.gitignore``, and ``README.md``. Does NOT create the host or any
     modules — those go under ``dest/host`` and ``dest/modules/`` afterwards.
+
+    ``preserve_existing`` lists top-level entry names that may already exist
+    in ``dest``; the scaffold's copy is skipped and the preserved path is
+    included in the returned list. Other pre-existing entries raise
+    ``FileExistsError``.
     """
     dest = Path(dest)
-    dest.mkdir(parents=True, exist_ok=True)
-    _apply_template_files(
+    _require_empty_dest(dest, preserve_existing=preserve_existing)
+    preserved = _apply_template_files(
         _resolve_template_root("workspace", template_root),
         dest,
-        {"{{HOST_NAME}}": to_kebab_case(name)},
+        {
+            "{{HOST_NAME}}": validate_scaffold_name(name),
+            "{{HOST_PYPI_NAME}}": to_kebab_case(name),
+        },
+        preserve_existing=preserve_existing,
     )
     logger.info("Scaffolded workspace root at %s", dest)
-    return dest
+    return preserved
 
 
 def create_host(
@@ -112,23 +160,31 @@ def create_host(
     modules: Sequence[str],
     template_root: Path | None = None,
     framework_version: str = "*",
-) -> Path:
+    *,
+    preserve_existing: frozenset[str] = frozenset(),
+) -> list[Path]:
+    """Scaffold a host project at ``dest``; return preserved pre-existing paths.
+
+    ``preserve_existing`` semantics match :func:`create_workspace`.
+    """
     dest = Path(dest)
-    _require_empty_dest(dest)
+    _require_empty_dest(dest, preserve_existing=preserve_existing)
     module_dep_lines = "\n".join(f'    "{_module_to_pypi_name(m)}>=0.1,<1.0",' for m in modules)
-    _apply_template_files(
+    preserved = _apply_template_files(
         _resolve_template_root("host", template_root),
         dest,
         {
-            "{{HOST_NAME}}": name,
+            "{{HOST_NAME}}": validate_scaffold_name(name),
+            "{{HOST_PYPI_NAME}}": to_kebab_case(name),
             "{{MODULE_DEPS}}": module_dep_lines,
             "{{FRAMEWORK_VERSION}}": framework_version,
         },
+        preserve_existing=preserve_existing,
     )
     logger.info(
         "Scaffolded host '%s' at %s (modules: %s)", name, dest, ", ".join(modules) or "<none>"
     )
-    return dest
+    return preserved
 
 
 def create_module(

{simple_module_cli-0.0.12 → simple_module_cli-0.0.13}/simple_module_cli/templates/host/client_app/package.json.tpl

@@ -1,5 +1,5 @@
 {
-  "name": "{{HOST_NAME}}-client-app",
+  "name": "{{HOST_PYPI_NAME}}-client-app",
   "private": true,
   "type": "module",
   "scripts": {

simple_module_cli-0.0.13/simple_module_cli/templates/host/client_app/pages/Landing.tsx

@@ -0,0 +1,78 @@
+/**
+ * Landing page for the public root (`/`).
+ *
+ * Scaffolded by `smpy new` so a fresh app boots straight to a friendly
+ * page instead of a 404. Replace or restyle as your app's front door
+ * takes shape — the only contract is that something renders at "/".
+ */
+
+type LandingProps = {
+  isAuthenticated: boolean;
+};
+
+export default function Landing({ isAuthenticated }: LandingProps) {
+  const primaryHref = isAuthenticated ? '/dashboard' : '/users/login';
+  const primaryLabel = isAuthenticated ? 'Open dashboard' : 'Sign in';
+
+  return (
+    <main className="mx-auto flex min-h-screen max-w-2xl flex-col justify-center gap-8 px-6 py-16">
+      <header className="space-y-3">
+        <p className="text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground">
+          simple_module_py
+        </p>
+        <h1 className="text-4xl font-bold tracking-tight sm:text-5xl">
+          Your app is up.
+        </h1>
+        <p className="text-base text-muted-foreground sm:text-lg">
+          This is the host's landing page — generated by{' '}
+          <code className="rounded bg-secondary px-1.5 py-0.5 font-mono text-sm">smpy new</code>.
+          Edit{' '}
+          <code className="rounded bg-secondary px-1.5 py-0.5 font-mono text-sm">
+            client_app/pages/Landing.tsx
+          </code>{' '}
+          to make it yours.
+        </p>
+      </header>
+
+      <div className="flex flex-wrap gap-3">
+        <a
+          href={primaryHref}
+          className="inline-flex items-center justify-center rounded-md bg-primary px-5 py-2.5 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90"
+        >
+          {primaryLabel}
+        </a>
+        <a
+          href="https://github.com/antosubash/simple_module_python"
+          className="inline-flex items-center justify-center rounded-md border border-border bg-background px-5 py-2.5 text-sm font-medium transition-colors hover:bg-secondary"
+        >
+          Read the docs
+        </a>
+      </div>
+
+      <section className="rounded-xl border border-border bg-card p-5">
+        <h2 className="mb-3 text-sm font-semibold">Next steps</h2>
+        <ul className="space-y-2 text-sm text-muted-foreground">
+          <li>
+            Create an admin:{' '}
+            <code className="rounded bg-secondary px-1.5 py-0.5 font-mono text-[13px] text-foreground">
+              uv run smpy users create-admin
+            </code>
+          </li>
+          <li>
+            Scaffold a module:{' '}
+            <code className="rounded bg-secondary px-1.5 py-0.5 font-mono text-[13px] text-foreground">
+              smpy create-module orders --dest modules/orders
+            </code>
+          </li>
+          <li>
+            Sign in at{' '}
+            <a href="/users/login" className="font-mono text-[13px] text-primary hover:underline">
+              /users/login
+            </a>{' '}
+            and explore the dashboard.
+          </li>
+        </ul>
+      </section>
+    </main>
+  );
+}