create-caspian-app 1.5.4 → 1.5.5

package/dist/AGENTS.md

@@ -312,7 +312,7 @@ Use `.github/copilot-instructions.md` for the repo-wide implementation rules. Th
 - Use `node_modules/caspian-utils/dist/docs/file-conventions.md` for the general special-file model, then verify the completed Python migration in `main.py` and `.venv/Lib/site-packages/casp/**`: routes use `index.py`, layouts use `layout.py`, navigation loading UI uses `loading.py`, and global fallback pages use `not_found.py` and `error.py`. This app has no authored `.html` special files.
 - **If navigation loading UI is wanted, it is `loading.py` — never hand-roll it.** The file itself is optional and most subtrees do not have one; this rule governs the implementation, not whether to add the feature. A spinner component, a global `isLoading` store, a `pp:navigation:start`/`pp:navigation:complete` listener, or a manual overlay built for route-to-route navigation is a reimplementation of the shipped runtime (`casp/loading.py` collects the files, `caspian_config.py` derives their URL scopes, the browser runtime resolves the closest ancestor scope and swaps the `pp-loading-content="true"` pane). The full contract is in the "Special files" block above; the shipped example is `src/app/dashboard/loading.py` plus the `pp-loading-content="true"` bar in `src/app/dashboard/layout.py`. In-page waits (RPC, submit, filter, upload) are `pp.state` in the owning component and are not this feature.
 - When `caspian.config.json` has `prisma: true`, database reads and writes from Python routes, layouts, RPC actions, upload flows, auth flows, and helpers must use the generated Prisma Python ORM in `src/lib/prisma/**`. Do not create a separate database fetch layer with raw drivers, hand-written SQL helpers, JSON manifests, app-specific HTTP fetches, or browser-side data fetches to replace the ORM. Use raw SQL only as a narrow Prisma ORM fallback when the generated client cannot express a query clearly.
-- Development restarts must preserve the database lifecycle. `settings/python-server.ts` sends an authenticated shutdown command through a private child stdin pipe and waits for Uvicorn to exit before force-kill is considered; `main.py` handles that command with `uvicorn.Server.should_exit`, and, only when `cfg.prisma` is true, conditionally imports the generated client and registers a Prisma lifespan that awaits `prisma.disconnect()` during shutdown. A Prisma-disabled project may have no `src.lib.prisma` package, so never move that import outside the feature gate. Keep Prisma's lifespan ahead of later lifespans so it exits last, do not make it connect eagerly, and do not replace the normal restart path with immediate `taskkill /F` / `SIGKILL`—that bypasses FastAPI cleanup and churns database connections during source edits.
+- Development restarts must preserve the database lifecycle. `settings/python-server.ts` sends an authenticated shutdown command through a private child stdin pipe and waits for Uvicorn to exit before force-kill is considered; `main.py` handles that command with `uvicorn.Server.should_exit`, and, only when `cfg.prisma` is true, conditionally imports the generated client and registers a Prisma lifespan that awaits `prisma.disconnect()` during shutdown. **Two independent conditions gate that import, not one.** `cfg.prisma` says the feature is _enabled_; `src/lib/prisma/` existing on disk says the ORM has actually been _generated_. A Prisma-disabled project has no such package, and neither does a freshly scaffolded or freshly cloned project whose `prisma/schema.prisma` exists but where `npx ppy generate` has never run — so the import is guarded by `PRISMA_PACKAGE_DIR.is_dir()` inside the `cfg.prisma` gate, and the lifespan is registered on `prisma is not None` rather than on the flag. Never move the import outside either guard, and do not collapse them back into one: a bare `ModuleNotFoundError` at import kills the dev stack before a single route renders, with a traceback that names no fix. A directory that exists but fails to import is a genuinely broken install (missing driver dependency, half-written generation) and keeps its own traceback. Missing-and-enabled warns and keeps serving in development but raises at boot in production, where every database call would fail at request time anyway — the same fail-closed rule as `APP_ENV`. Every consumer must therefore treat `main.prisma` as possibly `None`. Keep Prisma's lifespan ahead of later lifespans so it exits last, do not make it connect eagerly, and do not replace the normal restart path with immediate `taskkill /F` / `SIGKILL`—that bypasses FastAPI cleanup and churns database connections during source edits.
 - **After any `prisma/schema.prisma` change, exactly two commands are required, in order.** Step 1 — sync the database, pick one: `npx prisma migrate dev` (development default, creates and applies a migration) or `npx prisma db push` (migration-less direct sync). Step 2 — always: `npx ppy generate`, the **only** command that regenerates the Python ORM the app imports (`src/lib/prisma/__init__.py`, `db.py`, `models.py`, `settings/prisma-schema.json`). The two generators are different toolchains from the same schema: `npx prisma generate` builds the Node/TypeScript `@prisma/client` used only by `prisma/seed.ts` and writes zero Python — it is never a substitute for `npx ppy generate`. Never hand-write or patch the generated Python ORM instead of regenerating it; the generated client is ready to import from `src.lib.prisma`. See `node_modules/caspian-utils/dist/docs/database.md` "Two Generators, One Schema".
 - Treat `npx prisma db seed` as a delicate, potentially destructive operation. In this workspace, seed scripts may clear tables before inserting fresh records. Before running that command, an AI agent must propose the exact command, warn that it can delete or overwrite database data including production data if the datasource is wrong, confirm the datasource when practical, and wait for explicit user approval.
 - Component-first page composition is the highest-priority authoring rule for this workspace (see `.github/copilot-instructions.md`). Build pages as a short assembly of `x-*` chunk components (top menu, sidebar, header, content sections, cards, forms, footer) and keep each chunk's long markup inside its own focused single-file `html(...)` component, so the page template in `src/app/**/index.py` stays small instead of holding a wall of HTML. Plan the chunk breakdown before writing the route, not as a later cleanup pass.

package/dist/main.py

@@ -81,19 +81,55 @@ from collections.abc import Callable
 load_dotenv()
 cfg = get_config()
 
-# Prisma is optional. A project generated with `prisma: false` has no
-# `src.lib.prisma` package, so both the import and lifespan registration must be
-# behind the feature gate.
-prisma: Any = None
-if cfg.prisma:
-    from src.lib.prisma import prisma as configured_prisma
+# Declared before the Prisma and MCP blocks below, which need it to decide
+# whether a missing generated client, an unauthenticated endpoint, or an open
+# CORS policy is tolerable. Resolved fail-closed: only an explicit development
+# APP_ENV turns the relaxations on.
+IS_PRODUCTION = is_production_environment()
 
-    prisma = configured_prisma
+# Prisma is optional, and its Python ORM is *generated* rather than authored, so
+# there are two independent conditions -- the feature flag in
+# `caspian.config.json`, and whether `npx ppy generate` has actually produced
+# `src/lib/prisma/`. A project generated with `prisma: false` has no such
+# package; neither does a freshly cloned or freshly scaffolded project whose
+# schema exists but has never been generated. Both must leave the app importable,
+# so the import, the lifespan registration, and every consumer treat `prisma` as
+# possibly `None`.
+PRISMA_PACKAGE_DIR = Path(__file__).resolve().parent / "src" / "lib" / "prisma"
+
+PRISMA_NOT_GENERATED_MESSAGE = (
+    "Prisma is enabled in caspian.config.json but the Python ORM has not been "
+    "generated, so src/lib/prisma/ does not exist. Sync the database with "
+    "`npx prisma migrate dev` (or `npx prisma db push`), then run "
+    "`npx ppy generate` to generate the client."
+)
 
-# Declared before the MCP block below, which needs it to decide whether an
-# unauthenticated endpoint or an open CORS policy is tolerable. Resolved
-# fail-closed: only an explicit development APP_ENV turns the relaxations on.
-IS_PRODUCTION = is_production_environment()
+prisma: Any = None
+if cfg.prisma:
+    if PRISMA_PACKAGE_DIR.is_dir():
+        # Present but unimportable is a genuinely broken install (a missing
+        # driver dependency, a half-written generation). Let that traceback
+        # through rather than degrading to a confusing "not generated" hint.
+        # The ignore matches the optional MCP import below: a generated module
+        # is absent from a static checkout, so the type checker cannot see it.
+        from src.lib.prisma import prisma as configured_prisma  # type: ignore[import-not-found]
+
+        prisma = configured_prisma
+    elif IS_PRODUCTION:
+        # A deployment that enabled Prisma and shipped without the generated
+        # client is broken: every database call would fail at request time.
+        # Fail at boot instead, consistent with the fail-closed APP_ENV rule.
+        raise RuntimeError(PRISMA_NOT_GENERATED_MESSAGE)
+    else:
+        # In development this is the ordinary "I have not generated it yet"
+        # state. Warn once at boot and keep serving, so the dev stack does not
+        # die with a bare ModuleNotFoundError before a single route renders.
+        print(
+            f"[caspian] WARNING: {PRISMA_NOT_GENERATED_MESSAGE} "
+            "Database access is unavailable until then; the rest of the app runs normally.",
+            file=sys.stderr,
+            flush=True,
+        )
 
 # Resolve APP_TIMEZONE once at import so an unknown zone name fails at boot with
 # a named error, rather than on whichever request first formats a date. Only the
@@ -324,7 +360,9 @@ def get_app_lifespans() -> list[LifespanFactory]:
 
     # Keep the database alive until every later lifespan has shut down. This does
     # not connect eagerly; it only guarantees cleanup when Uvicorn exits cleanly.
-    if cfg.prisma:
+    # Gated on the client being importable, not just on the feature flag: with
+    # Prisma enabled but not yet generated there is nothing to disconnect.
+    if prisma is not None:
         lifespans.append(prisma_lifespan)
 
     # MCP lifecycle

package/dist/tests/test_main_helpers.py

@@ -16,9 +16,21 @@ from conftest import run_async
 
 
 class TestPrismaLifespan:
-    def test_disconnects_on_shutdown(self, monkeypatch):
+    @staticmethod
+    def _install_client(monkeypatch) -> AsyncMock:
+        """Stand in for the generated Prisma client.
+
+        `src/lib/prisma/` is generated by `npx ppy generate`, so it is absent in
+        a fresh checkout and `main.prisma` is then `None`. The lifespan contract
+        is about whatever object `main.prisma` holds, so the tests supply one
+        rather than depending on generation having been run.
+        """
         disconnect = AsyncMock()
-        monkeypatch.setattr(main.prisma, "disconnect", disconnect)
+        monkeypatch.setattr(main, "prisma", SimpleNamespace(disconnect=disconnect))
+        return disconnect
+
+    def test_disconnects_on_shutdown(self, monkeypatch):
+        disconnect = self._install_client(monkeypatch)
 
         async def exercise_lifespan():
             async with main.prisma_lifespan(main.app):
@@ -29,12 +41,29 @@ class TestPrismaLifespan:
 
     def test_disabled_prisma_is_not_registered(self, monkeypatch):
         monkeypatch.setattr(main, "cfg", replace(main.cfg, prisma=False))
+        monkeypatch.setattr(main, "prisma", None)
 
         assert main.prisma_lifespan not in main.get_app_lifespans()
 
+    def test_enabled_but_ungenerated_prisma_is_not_registered(self, monkeypatch):
+        """Prisma enabled in config but never generated leaves nothing to close.
+
+        Registration is gated on the client being importable, not on the flag,
+        so the app still boots when `npx ppy generate` has not been run.
+        """
+        monkeypatch.setattr(main, "cfg", replace(main.cfg, prisma=True))
+        monkeypatch.setattr(main, "prisma", None)
+
+        assert main.prisma_lifespan not in main.get_app_lifespans()
+
+    def test_generated_prisma_is_registered(self, monkeypatch):
+        monkeypatch.setattr(main, "cfg", replace(main.cfg, prisma=True))
+        self._install_client(monkeypatch)
+
+        assert main.prisma_lifespan in main.get_app_lifespans()
+
     def test_disconnects_when_another_lifespan_raises(self, monkeypatch):
-        disconnect = AsyncMock()
-        monkeypatch.setattr(main.prisma, "disconnect", disconnect)
+        disconnect = self._install_client(monkeypatch)
 
         async def exercise_lifespan():
             try:
@@ -46,6 +75,21 @@ class TestPrismaLifespan:
         run_async(exercise_lifespan())
         disconnect.assert_awaited_once_with()
 
+    def test_lifespan_is_a_noop_without_a_generated_client(self, monkeypatch):
+        """The shutdown half must tolerate `prisma` being `None`.
+
+        `get_app_lifespans` already skips registration in that state, but the
+        lifespan is public and is exercised directly by tests and by anyone
+        composing lifespans by hand.
+        """
+        monkeypatch.setattr(main, "prisma", None)
+
+        async def exercise_lifespan():
+            async with main.prisma_lifespan(main.app):
+                pass
+
+        run_async(exercise_lifespan())
+
 
 class TestDevControlPipe:
     def test_valid_shutdown_command_stops_server(self):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-caspian-app",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "description": "Scaffold a new Caspian project (FastAPI-powered reactive Python framework).",
   "main": "dist/index.js",
   "type": "module",