simple-module-cli 0.0.36__tar.gz → 0.0.38__tar.gz

{simple_module_cli-0.0.36 → simple_module_cli-0.0.38}/.gitignore

@@ -7,8 +7,6 @@ build/
 .venv/
 *.egg
 
-# UV
-uv.lock
 
 # Node
 node_modules/
@@ -64,3 +62,5 @@ host/client_app/.playwright-cli/*
 .superpowers/
 .qa/
 .verify/
+/openapi.json
+qa-shots/

{simple_module_cli-0.0.36 → simple_module_cli-0.0.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_cli
-Version: 0.0.36
+Version: 0.0.38
 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.36 → simple_module_cli-0.0.38}/pyproject.toml

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

simple_module_cli-0.0.38/simple_module_cli/_add_install.py

@@ -0,0 +1,59 @@
+"""Post-install steps and shared helpers for ``smpy add``."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+
+import typer
+
+ExecRunner = Callable[[list[str], Path], int]
+
+
+_ENTRYPOINT_CHECK = (
+    "import sys\n"
+    "from importlib.metadata import distributions\n"
+    "target = sys.argv[1].replace('-', '_').lower()\n"
+    "for dist in distributions():\n"
+    "    if any(ep.group == 'simple_module' for ep in dist.entry_points):\n"
+    "        name = (dist.metadata['Name'] or '').replace('-', '_').lower()\n"
+    "        if name == target:\n"
+    "            sys.exit(0)\n"
+    "sys.exit(1)\n"
+)
+
+
+def _default_exec_runner(cmd: list[str], cwd: Path) -> int:
+    return subprocess.run(cmd, cwd=cwd, check=False).returncode
+
+
+def _fail(message: str) -> typer.Exit:
+    typer.echo(f"ERROR: {message}", err=True)
+    return typer.Exit(code=1)
+
+
+def post_install(
+    project_dir: Path,
+    dists: list[str],
+    models_dists: list[str],
+    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`.")
+    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)
+    for dist in dists:
+        code = exec_runner(["uv", "run", "python", "-c", _ENTRYPOINT_CHECK, dist], project_dir)
+        if code != 0:
+            raise _fail(
+                f"{dist} installed but exposes no [project.entry-points.simple_module] "
+                "entry point — it is not a SimpleModule module."
+            )
+    for dist in models_dists:
+        typer.echo(
+            f"{dist} ships database models — generate and apply the migration:\n"
+            f'  make migration msg="add {dist}"\n  make migrate'
+        )

simple_module_cli-0.0.38/simple_module_cli/_add_sources.py

@@ -0,0 +1,83 @@
+"""PyPI and local-path sources for ``smpy add``."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import typer
+
+from simple_module_cli._add_install import ExecRunner, _fail, post_install
+from simple_module_cli.git_source import derive_range, scan_modules
+from simple_module_cli.pyproject_edit import (
+    save_pyproject,
+    write_dependency,
+    write_path_source,
+    write_workspace_source,
+)
+from simple_module_cli.uv_workspace import is_workspace_member
+
+
+def _add_pypi(doc, pyproject: Path, raw: str, no_sync: bool, exec_runner: ExecRunner) -> list[str]:
+    name = raw
+    for i, ch in enumerate(raw):
+        if ch in "<>=!~[; ":
+            name = raw[:i]
+            break
+    constraint = raw[len(name) :]
+    write_dependency(doc, name, constraint)
+    save_pyproject(pyproject, doc)
+    typer.echo(f"Added {name} (PyPI).")
+    if not no_sync:
+        post_install(pyproject.parent, [name], [], exec_runner)
+    return [name]
+
+
+def _resolve_local_path(project_dir: Path, spec_path: Path) -> tuple[Path, str]:
+    """Resolve a local-path spec to ``(directory, text written to pyproject)``.
+
+    A relative path is resolved against the ``--path`` project (the pyproject
+    being edited, which is what ``[tool.uv.sources]`` paths are relative to).
+    If nothing exists there but the path exists relative to the cwd, the cwd
+    one is used and the written path is re-expressed relative to the project.
+    """
+    if spec_path.is_absolute():
+        return spec_path, str(spec_path)
+    root = project_dir / spec_path
+    if not root.exists() and (Path.cwd() / spec_path).exists():
+        root = Path.cwd() / spec_path
+        return root, os.path.relpath(root.resolve(), project_dir.resolve())
+    return root, str(spec_path)
+
+
+def _add_path(
+    doc, pyproject: Path, spec_path: Path, no_sync: bool, exec_runner: ExecRunner
+) -> list[str]:
+    root, written = _resolve_local_path(pyproject.parent, spec_path)
+    found = [m for m in scan_modules(root) if m.subdirectory is None]
+    if not found:
+        raise _fail(
+            f"{root} has no [project.entry-points.simple_module] entry point at its root "
+            f"(relative paths resolve against the --path project, {pyproject.parent}, "
+            "falling back to the current directory)"
+        )
+    mod = found[0]
+    if is_workspace_member(pyproject.parent, root):
+        # uv refuses a path source for a workspace member; the scaffold's own
+        # sample module is wired the same way (unpinned + workspace = true).
+        write_dependency(doc, mod.dist_name, "")
+        write_workspace_source(doc, mod.dist_name)
+        typer.echo(f"Added {mod.dist_name} (uv workspace member {written}).")
+    else:
+        write_dependency(doc, mod.dist_name, derive_range(mod.version))
+        write_path_source(doc, mod.dist_name, path=written)
+        typer.echo(f"Added {mod.dist_name} (editable path {written}).")
+    save_pyproject(pyproject, doc)
+    if not no_sync:
+        post_install(
+            pyproject.parent,
+            [mod.dist_name],
+            [mod.dist_name] if mod.ships_models else [],
+            exec_runner,
+        )
+    return [mod.dist_name]

simple_module_cli-0.0.38/simple_module_cli/_app_project_manifests.py

@@ -0,0 +1,94 @@
+"""Dependency pins, ``.env`` DB URLs and ``pyproject.toml`` rewriting for ``smpy new``."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from simple_module_cli.scaffolding import resolve_framework_version
+
+_FRAMEWORK_VERSION = resolve_framework_version()
+
+# 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). The lint /
+# test tooling (ruff, ty, pytest-*) backs the generated `make lint`/`make
+# test` targets so a fresh app can run its own quality gates.
+_APP_PY_DEV_DEPS = [
+    f"simple_module_test=={_FRAMEWORK_VERSION}",
+    f"simple_module_cli=={_FRAMEWORK_VERSION}",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-playwright>=0.7.2",
+    # Floor: unpinned, uv backtracks playwright to 1.18 (GH #445).
+    "playwright>=1.45",
+    "ruff>=0.8",
+    "ty>=0.0.29",
+]
+
+_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": "^3.7.0",
+}
+# Flat mode has no npm workspaces, so `client_app/package.json` is never
+# installed — the root package.json seeded from these two dicts is the only
+# manifest npm reads. It must therefore cover everything client_app needs to
+# build, not just the framework pins: `vite.config.ts` imports
+# `@tailwindcss/vite`, and `tsc` needs the @types packages. Keep this in step
+# with templates/host/client_app/package.json.tpl.
+_APP_NPM_DEV_DEPS = {
+    "@simple-module-py/tsconfig": _FRAMEWORK_VERSION,
+    "@tailwindcss/vite": "^4.0.0",
+    "@types/node": "^26.5.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.2",
+}
+
+
+def _db_url(db: str, db_name: str, *, flat: bool, password: str = "<POSTGRES_PASSWORD>") -> str:
+    if db == "postgres":
+        return f"postgresql+asyncpg://postgres:{password}@localhost:5432/{db_name}"
+    # Workspace mode keeps the SQLite file next to host/'s alembic.ini so
+    # `cd host && uvicorn` and `cd host && alembic` resolve the same path.
+    return "sqlite+aiosqlite:///./app.db" if flat else "sqlite+aiosqlite:///./host/app.db"
+
+
+def _rewrite_pyproject(
+    text: str,
+    deps: list[str],
+    dev_deps: list[str],
+    *,
+    sources: Sequence[str] = (),
+    project_name: str | None = None,
+) -> str:
+    """Replace deps in a host ``pyproject.toml`` and pin workspace sources.
+
+    ``sources`` lists ``simple_module_*`` packages that should resolve from
+    the uv workspace (``modules/*``) instead of PyPI. Emits a
+    ``[tool.uv.sources]`` block per entry. Empty in flat mode.
+
+    ``project_name`` overrides ``[project].name`` — set in workspace mode
+    so the host's package name differs from the workspace root's.
+    """
+    import tomlkit
+
+    doc = tomlkit.parse(text)
+    project = doc.setdefault("project", tomlkit.table())
+    if project_name is not None:
+        project["name"] = project_name
+    project["dependencies"] = list(deps)
+    groups = doc.setdefault("dependency-groups", tomlkit.table())
+    groups["dev"] = list(dev_deps)
+    if sources:
+        tool = doc.setdefault("tool", tomlkit.table())
+        uv_table = tool.setdefault("uv", tomlkit.table())
+        uv_sources = uv_table.setdefault("sources", tomlkit.table())
+        for src in sources:
+            uv_sources[src] = {"workspace": True}
+    return tomlkit.dumps(doc)

{simple_module_cli-0.0.36 → simple_module_cli-0.0.38}/simple_module_cli/_env.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-__all__ = ["set_env_key"]
+__all__ = ["env_values", "set_env_key"]
 
 
 def set_env_key(text: str, key: str, value: str) -> str:
@@ -10,3 +10,10 @@ def set_env_key(text: str, key: str, value: str) -> str:
     lines = [ln for ln in text.splitlines() if not ln.startswith(f"{key}=")]
     lines.append(f"{key}={value}")
     return "\n".join(lines) + "\n"
+
+
+def env_values(text: str) -> dict[str, str]:
+    """Parse the ``KEY=VALUE`` lines of an env-style file body (comments skipped)."""
+    lines = text.splitlines()
+    pairs = (ln.split("=", 1) for ln in lines if "=" in ln and not ln.lstrip().startswith("#"))
+    return {key.strip(): value for key, value in pairs}

simple_module_cli-0.0.38/simple_module_cli/_local_env.py

@@ -0,0 +1,83 @@
+"""Split a new app's env file into a committed template and a local ``.env``.
+
+``.env.example`` is committed, so it only ever carries placeholders. The
+secrets ``smpy new`` generates go to ``.env``, which every scaffold's
+``.gitignore`` excludes (GH #441). An existing ``.env`` is never overwritten:
+only keys it does not define yet are added.
+"""
+
+from __future__ import annotations
+
+import secrets
+from collections.abc import Iterable
+from pathlib import Path
+
+from simple_module_cli._env import env_values, set_env_key
+
+__all__ = ["add_postgres_password_placeholder", "comment_out_env_key", "write_local_env"]
+
+_PG_PASSWORD_NOTE = (
+    "# Compose puts this into SM_DATABASE_URL unencoded: use only URL-safe\n"
+    "# characters (letters, digits, - _ . ~). `make docker-up` rejects others (GH #472).\n"
+)
+
+_SECRET_NOTE = (
+    "# Secrets — `smpy new` generated these into .env (gitignored); keep them\n"
+    "# out of this committed file. Set real values wherever you deploy."
+)
+
+
+def comment_out_env_key(text: str, key: str) -> str:
+    """Turn ``KEY=...`` into a bare ``# KEY=`` placeholder, in place if present."""
+    lines = text.splitlines()
+    placeholder = f"# {key}="
+    hits = [i for i, ln in enumerate(lines) if ln.startswith((f"{key}=", placeholder))]
+    if hits:
+        lines[hits[0]] = placeholder
+        lines = [ln for i, ln in enumerate(lines) if i not in hits[1:]]
+    else:
+        if _SECRET_NOTE.splitlines()[0] not in lines:
+            lines += ["", *_SECRET_NOTE.splitlines()]
+        lines.append(placeholder)
+    return "\n".join(lines) + "\n"
+
+
+def add_postgres_password_placeholder(text: str) -> str:
+    """Add an empty ``POSTGRES_PASSWORD=`` to ``.env.example``, with its URL-safe note."""
+    text = set_env_key(text, "POSTGRES_PASSWORD", "")
+    return text.replace("POSTGRES_PASSWORD=\n", _PG_PASSWORD_NOTE + "POSTGRES_PASSWORD=\n", 1)
+
+
+def write_local_env(
+    target: Path, *, secret_keys: Iterable[str], overrides: dict[str, str] | None = None
+) -> None:
+    """Write ``target/.env`` from ``.env.example`` plus generated secrets.
+
+    ``secret_keys`` get a fresh random value each; ``overrides`` are written
+    verbatim (e.g. a database URL carrying a generated password). Overrides
+    belong together, so an existing ``.env`` defining any of them gets none:
+    a fresh URL must not disagree with a kept ``POSTGRES_PASSWORD``.
+    """
+    env_path = target / ".env"
+    existing = env_path.exists()
+    source = env_path if existing else target / ".env.example"
+    text = source.read_text(encoding="utf-8") if source.exists() else ""
+    defined = env_values(text).keys()
+    overrides = overrides or {}
+    if existing and defined & overrides.keys():
+        overrides = {}
+    values = {key: secrets.token_urlsafe(32) for key in secret_keys} | overrides
+    for key, value in values.items():
+        if existing and key in defined:
+            continue
+        placeholder = f"# {key}="
+        lines = text.splitlines()
+        if placeholder in lines:
+            # Line-based, so a placeholder on the last line (no trailing
+            # newline) is handled too.
+            lines[lines.index(placeholder)] = f"{key}={value}"
+            text = "\n".join(lines) + "\n"
+        else:
+            text = set_env_key(text, key, value)
+    env_path.write_text(text, encoding="utf-8")
+    env_path.chmod(0o600)  # holds generated secrets

{simple_module_cli-0.0.36 → simple_module_cli-0.0.38}/simple_module_cli/add_cmd.py

@@ -11,14 +11,19 @@ sync-js-deps`` → entry-point verification, unless ``--no-sync``.
 
 from __future__ import annotations
 
-import subprocess
 import tempfile
-from collections.abc import Callable
 from pathlib import Path
 from typing import Annotated
 
 import typer
 
+from simple_module_cli._add_install import (
+    ExecRunner,
+    _default_exec_runner,
+    _fail,
+    post_install,
+)
+from simple_module_cli._add_sources import _add_path, _add_pypi
 from simple_module_cli.git_source import (
     FoundModule,
     SpecError,
@@ -34,39 +39,15 @@ from simple_module_cli.pyproject_edit import (
     save_pyproject,
     write_dependency,
     write_git_source,
-    write_path_source,
 )
 
 __all__ = ["ExecRunner", "add_module", "post_install", "run_add"]
 
-ExecRunner = Callable[[list[str], Path], int]
-
 _SECURITY_NOTICE = (
     "note: this installs and runs code from a URL you chose — review the "
     "repository before booting the host."
 )
 
-_ENTRYPOINT_CHECK = (
-    "import sys\n"
-    "from importlib.metadata import distributions\n"
-    "target = sys.argv[1].replace('-', '_').lower()\n"
-    "for dist in distributions():\n"
-    "    if any(ep.group == 'simple_module' for ep in dist.entry_points):\n"
-    "        name = (dist.metadata['Name'] or '').replace('-', '_').lower()\n"
-    "        if name == target:\n"
-    "            sys.exit(0)\n"
-    "sys.exit(1)\n"
-)
-
-
-def _default_exec_runner(cmd: list[str], cwd: Path) -> int:
-    return subprocess.run(cmd, cwd=cwd, check=False).returncode
-
-
-def _fail(message: str) -> typer.Exit:
-    typer.echo(f"ERROR: {message}", err=True)
-    return typer.Exit(code=1)
-
 
 def _choose(
     found: list[FoundModule],
@@ -96,69 +77,6 @@ def _choose(
     ]
 
 
-def post_install(
-    project_dir: Path,
-    dists: list[str],
-    models_dists: list[str],
-    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`.")
-    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)
-    for dist in dists:
-        code = exec_runner(["uv", "run", "python", "-c", _ENTRYPOINT_CHECK, dist], project_dir)
-        if code != 0:
-            raise _fail(
-                f"{dist} installed but exposes no [project.entry-points.simple_module] "
-                "entry point — it is not a SimpleModule module."
-            )
-    for dist in models_dists:
-        typer.echo(
-            f"{dist} ships database models — generate and apply the migration:\n"
-            f'  make migration msg="add {dist}"\n  make migrate'
-        )
-
-
-def _add_pypi(doc, pyproject: Path, raw: str, no_sync: bool, exec_runner: ExecRunner) -> list[str]:
-    name = raw
-    for i, ch in enumerate(raw):
-        if ch in "<>=!~[; ":
-            name = raw[:i]
-            break
-    constraint = raw[len(name) :]
-    write_dependency(doc, name, constraint)
-    save_pyproject(pyproject, doc)
-    typer.echo(f"Added {name} (PyPI).")
-    if not no_sync:
-        post_install(pyproject.parent, [name], [], exec_runner)
-    return [name]
-
-
-def _add_path(
-    doc, pyproject: Path, spec_path: Path, no_sync: bool, exec_runner: ExecRunner
-) -> list[str]:
-    root = spec_path if spec_path.is_absolute() else pyproject.parent / spec_path
-    found = [m for m in scan_modules(root) if m.subdirectory is None]
-    if not found:
-        raise _fail(f"{root} has no [project.entry-points.simple_module] entry point at its root")
-    mod = found[0]
-    write_dependency(doc, mod.dist_name, derive_range(mod.version))
-    write_path_source(doc, mod.dist_name, path=str(spec_path))
-    save_pyproject(pyproject, doc)
-    typer.echo(f"Added {mod.dist_name} (editable path {spec_path}).")
-    if not no_sync:
-        post_install(
-            pyproject.parent,
-            [mod.dist_name],
-            [mod.dist_name] if mod.ships_models else [],
-            exec_runner,
-        )
-    return [mod.dist_name]
-
-
 def run_add(
     spec: str,
     *,

{simple_module_cli-0.0.36 → simple_module_cli-0.0.38}/simple_module_cli/app_project.py

@@ -19,8 +19,21 @@ from collections.abc import Sequence
 from pathlib import Path
 from typing import Any
 
+from simple_module_cli._app_project_manifests import (
+    _APP_NPM_DEPS,
+    _APP_NPM_DEV_DEPS,
+    _APP_PY_DEV_DEPS,
+    _FRAMEWORK_VERSION,
+    _db_url,
+    _rewrite_pyproject,
+)
 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._local_env import (
+    add_postgres_password_placeholder,
+    comment_out_env_key,
+    write_local_env,
+)
+from simple_module_cli.case import to_kebab_case, to_pascal_case, to_snake_case
 from simple_module_cli.catalog import CATALOG, PRESETS, expand_deps
 from simple_module_cli.docker_assets import scaffold_docker_assets
 from simple_module_cli.recipes import RECIPES, ScaffoldCtx
@@ -30,7 +43,6 @@ from simple_module_cli.scaffolding import (
     create_host,
     create_module,
     create_workspace,
-    resolve_framework_version,
 )
 
 __all__ = ["create_app_project"]
@@ -38,49 +50,6 @@ __all__ = ["create_app_project"]
 _SAMPLE_MODULE_NAME = "hello"
 _SAMPLE_MODULE_PKG = _module_to_pypi_name(_SAMPLE_MODULE_NAME)
 
-
-_FRAMEWORK_VERSION = resolve_framework_version()
-
-# 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). The lint /
-# test tooling (ruff, ty, pytest-*) backs the generated `make lint`/`make
-# test` targets so a fresh app can run its own quality gates.
-_APP_PY_DEV_DEPS = [
-    f"simple_module_test=={_FRAMEWORK_VERSION}",
-    f"simple_module_cli=={_FRAMEWORK_VERSION}",
-    "pytest>=8.0",
-    "pytest-asyncio>=0.24",
-    "pytest-playwright>=0.7.2",
-    "ruff>=0.8",
-    "ty>=0.0.29",
-]
-
-_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": "^3.7.0",
-}
-# Flat mode has no npm workspaces, so `client_app/package.json` is never
-# installed — the root package.json seeded from these two dicts is the only
-# manifest npm reads. It must therefore cover everything client_app needs to
-# build, not just the framework pins: `vite.config.ts` imports
-# `@tailwindcss/vite`, and `tsc` needs the @types packages. Keep this in step
-# with templates/host/client_app/package.json.tpl.
-_APP_NPM_DEV_DEPS = {
-    "@simple-module-py/tsconfig": _FRAMEWORK_VERSION,
-    "@tailwindcss/vite": "^4.0.0",
-    "@types/node": "^26.5.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "@vitejs/plugin-react": "^6.1.1",
-    "tailwindcss": "^4.0.0",
-    "typescript": "^7.0.2",
-    "vite": "^8.2.2",
-}
-
 # Files the host template ships that the workspace template re-emits at
 # the project root. Host copies are stripped in workspace mode.
 _HOST_FILES_OWNED_BY_WORKSPACE = (
@@ -150,19 +119,33 @@ def create_app_project(
         py_deps.append(_SAMPLE_MODULE_PKG)
         workspace_sources.append(_SAMPLE_MODULE_PKG)
 
-    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))
+    # Generated secrets go to the gitignored .env, never the committed
+    # .env.example (GH #441) — see write_local_env below.
+    secret_keys = ["SM_SECRET_KEY"]
     if "users" in resolved:
         # UsersSettings refuses its placeholder token secrets when
         # SM_ENVIRONMENT=production — the mode the compose containers run
-        # in — so generate real ones, same as SM_SECRET_KEY above.
-        for key in (
+        # in — so generate real ones, same as SM_SECRET_KEY.
+        secret_keys += [
             "SM_USERS_RESET_PASSWORD_TOKEN_SECRET",
             "SM_USERS_VERIFICATION_TOKEN_SECRET",
-        ):
-            env_text = set_env_key(env_text, key, _secrets.token_urlsafe(32))
-    env_text = set_env_key(env_text, "SM_DATABASE_URL", _db_url(db, to_kebab_case(name), flat=flat))
+        ]
+    db_name = to_snake_case(name)
+    env_path = target / ".env.example"
+    env_text = env_path.read_text(encoding="utf-8") if env_path.exists() else ""
+    for key in secret_keys:
+        env_text = comment_out_env_key(env_text, key)
+    local_overrides: dict[str, str] = {}
+    if db == "postgres":
+        # The compose `postgres` service takes its password from .env, and
+        # the dev SM_DATABASE_URL must match it (GH #444).
+        env_text = add_postgres_password_placeholder(env_text)
+        password = _secrets.token_urlsafe(24)
+        local_overrides = {
+            "POSTGRES_PASSWORD": password,
+            "SM_DATABASE_URL": _db_url(db, db_name, flat=flat, password=password),
+        }
+    env_text = set_env_key(env_text, "SM_DATABASE_URL", _db_url(db, db_name, flat=flat))
     env_text = set_env_key(env_text, "SM_MULTI_TENANT", "true" if tenancy else "false")
     env_path.write_text(env_text, encoding="utf-8")
 
@@ -198,6 +181,8 @@ def create_app_project(
             RECIPES[recipe_key].apply(target, ctx)
 
     scaffold_docker_assets(target, ctx, flat=flat)
+    # Last, so .env picks up every key the recipes added to .env.example.
+    write_local_env(target, secret_keys=secret_keys, overrides=local_overrides)
 
     return host_dir, preserved
 
@@ -232,46 +217,3 @@ def _seed_static_dist_placeholder(static_dist: Path) -> None:
     # an empty placeholder keeps `uv sync` from failing before vite build runs.
     static_dist.mkdir(parents=True, exist_ok=True)
     (static_dist / ".gitkeep").touch()
-
-
-def _db_url(db: str, slug: str, *, flat: bool) -> str:
-    if db == "postgres":
-        return f"postgresql+asyncpg://postgres:postgres@localhost:5432/{slug}"
-    # Workspace mode keeps the SQLite file next to host/'s alembic.ini so
-    # `cd host && uvicorn` and `cd host && alembic` resolve the same path.
-    return "sqlite+aiosqlite:///./app.db" if flat else "sqlite+aiosqlite:///./host/app.db"
-
-
-def _rewrite_pyproject(
-    text: str,
-    deps: list[str],
-    dev_deps: list[str],
-    *,
-    sources: Sequence[str] = (),
-    project_name: str | None = None,
-) -> str:
-    """Replace deps in a host ``pyproject.toml`` and pin workspace sources.
-
-    ``sources`` lists ``simple_module_*`` packages that should resolve from
-    the uv workspace (``modules/*``) instead of PyPI. Emits a
-    ``[tool.uv.sources]`` block per entry. Empty in flat mode.
-
-    ``project_name`` overrides ``[project].name`` — set in workspace mode
-    so the host's package name differs from the workspace root's.
-    """
-    import tomlkit
-
-    doc = tomlkit.parse(text)
-    project = doc.setdefault("project", tomlkit.table())
-    if project_name is not None:
-        project["name"] = project_name
-    project["dependencies"] = list(deps)
-    groups = doc.setdefault("dependency-groups", tomlkit.table())
-    groups["dev"] = list(dev_deps)
-    if sources:
-        tool = doc.setdefault("tool", tomlkit.table())
-        uv_table = tool.setdefault("uv", tomlkit.table())
-        uv_sources = uv_table.setdefault("sources", tomlkit.table())
-        for src in sources:
-            uv_sources[src] = {"workspace": True}
-    return tomlkit.dumps(doc)