create-caspian-app 1.4.7 → 1.5.1

package/dist/.github/copilot-instructions.md

@@ -49,6 +49,8 @@ This is the top architectural requirement for this workspace. Treat it as a hard
 - Let the running dev stack own generated outputs such as `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files. Treat those as generated artifacts rather than authored source.
 - Never treat `__pycache__/` directories or `.pyc` files as files to edit, regenerate on purpose, or keep in the final diff.
 - Treat `settings/component-map.json` and `settings/files-list.json` as generated outputs owned by `settings/component-map.ts` and `settings/files-list.ts`; inspect them when needed, but do not hand-edit them.
+- Keep development Python restarts graceful. `settings/python-server.ts` gives each child a private stdin control token and requests shutdown over that pipe before using force-kill as a timeout fallback; `main.py` translates the authenticated command into `uvicorn.Server.should_exit`. This ordering is what lets FastAPI lifespans close resources, especially the generated Prisma pool. Do not switch routine restarts back to immediate `taskkill /F` / `SIGKILL`, do not expose the control token over HTTP, and keep the child stdin pipe private to the orchestrator.
+- When Prisma is enabled, keep both the `src.lib.prisma` import and `prisma_lifespan` registration behind `cfg.prisma` in `main.py`; a Prisma-disabled project may not contain that generated package. Entering the lifespan must remain lazy (no development connection is opened merely by startup), while shutdown must always await `prisma.disconnect()` so pooled connections close before the Python process exits.
 - When `caspian.config.json` has `mcp: true`, treat `src/lib/mcp/mcp_server.py` as the app-owned FastMCP server and `src/lib/mcp/fastmcp.json` as the default MCP config. Use `npm run mcp` or `fastmcp run src/lib/mcp/fastmcp.json`; do not assume root `fastmcp.json` auto-discovery.
 - Keep auth policy in `src/lib/auth/auth_config.py` and keep auth bootstrap, middleware wiring, and provider registration in `main.py`.
 - Treat `casp.runtime_security` in `.venv/Lib/site-packages/casp/runtime_security.py` as package-owned runtime support for safe public-file serving: `PublicFilesMiddleware` maps every existing nested `public/**` file to its root-relative URL without per-directory routes, handles only `GET`/`HEAD`, rejects traversal and symlink escape, and falls through for missing files. It also owns restricted inline-media handling for configured user-upload directories, production session-secret enforcement, production-safe error messaging, fail-closed `APP_ENV` resolution via `is_production_environment()`, and baseline response headers including the Content-Security-Policy. Users should not customize this file during normal app work.

package/dist/AGENTS.md

@@ -289,6 +289,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.
 - **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

@@ -12,6 +12,8 @@ import os
 import importlib.util
 import re
 import secrets
+import sys
+import threading
 import traceback
 import json
 import math
@@ -79,6 +81,15 @@ 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
+
+    prisma = configured_prisma
+
 # 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.
@@ -270,6 +281,21 @@ setup_auth()
 LifespanFactory = Callable[[FastAPI], AbstractAsyncContextManager[Any]]
 
 
+@asynccontextmanager
+async def prisma_lifespan(_app: FastAPI):
+    """Close every generated Prisma connection during an orderly app shutdown.
+
+    The generated client connects lazily, so entering this lifespan does not open
+    a database connection. Its shutdown half is intentionally unconditional:
+    ``disconnect()`` is idempotent and also cleans up a partially initialized pool.
+    """
+    try:
+        yield
+    finally:
+        if prisma is not None:
+            await prisma.disconnect()
+
+
 def get_app_lifespans() -> list[LifespanFactory]:
     """
     Register all application lifespan handlers here.
@@ -296,6 +322,11 @@ def get_app_lifespans() -> list[LifespanFactory]:
     """
     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:
+        lifespans.append(prisma_lifespan)
+
     # MCP lifecycle
     # FastMCP needs its lifespan running so the MCP session manager starts.
     if mcp_app is not None:
@@ -1604,13 +1635,63 @@ app.add_middleware(SecurityHeadersMiddleware)
 if not IS_PRODUCTION:
     app.add_middleware(RequestDiagnosticsMiddleware)
 
+
+def _consume_dev_control_stream(
+    server: uvicorn.Server,
+    expected_token: str,
+    stream: Any,
+) -> None:
+    """Watch the private parent-process pipe for a graceful shutdown request."""
+    for raw_line in stream:
+        command, separator, token = raw_line.rstrip("\r\n").partition(":")
+        if separator and command == "shutdown" and secrets.compare_digest(token, expected_token):
+            server.should_exit = True
+            return
+
+    # The development orchestrator owns this process. If its control pipe closes,
+    # it has exited unexpectedly and the child must not remain orphaned.
+    server.should_exit = True
+
+
+def _start_dev_control_listener(
+    server: uvicorn.Server,
+    expected_token: str,
+) -> threading.Thread:
+    listener = threading.Thread(
+        target=_consume_dev_control_stream,
+        args=(server, expected_token, sys.stdin),
+        name="caspian-dev-control",
+        daemon=True,
+    )
+    listener.start()
+    return listener
+
+
 if __name__ == "__main__":
     port = int(os.getenv("PORT", 5091))
     workers = max(1, int(os.getenv("UVICORN_WORKERS", "1")))
-    uvicorn.run(
-        "main:app",
-        host="0.0.0.0",
-        port=port,
-        reload=False,
-        workers=workers,
-    )
+    dev_control_token = os.getenv("CASPIAN_DEV_CONTROL_TOKEN", "")
+
+    if dev_control_token:
+        # The local orchestrator uses a private stdin pipe so graceful shutdown
+        # works consistently on Windows, where SIGTERM is not available to Node
+        # child processes. Development intentionally remains single-worker.
+        server = uvicorn.Server(
+            uvicorn.Config(
+                "main:app",
+                host="0.0.0.0",
+                port=port,
+                reload=False,
+                workers=1,
+            )
+        )
+        _start_dev_control_listener(server, dev_control_token)
+        server.run()
+    else:
+        uvicorn.run(
+            "main:app",
+            host="0.0.0.0",
+            port=port,
+            reload=False,
+            workers=workers,
+        )

package/dist/settings/bs-config.ts

@@ -296,7 +296,7 @@ async function shutdown(exitCode: number): Promise<void> {
     bs.exit();
   }
 
-  stopPythonServer();
+  await stopPythonServer();
   process.exit(exitCode);
 }
 

package/dist/settings/python-server.ts

@@ -3,9 +3,12 @@ import { platform } from "os";
 import { existsSync } from "fs";
 import { join } from "path";
 import { Socket } from "net";
+import { randomBytes } from "crypto";
 
 let pythonProcess: ChildProcess | null = null;
+let pythonControlToken: string | null = null;
 let isRestarting = false;
+const GRACEFUL_SHUTDOWN_TIMEOUT_MS = 7000;
 
 function isWindows(): boolean {
   return platform() === "win32";
@@ -114,23 +117,68 @@ async function killProcessTree(child: ChildProcess): Promise<void> {
   }
 }
 
+export function requestGracefulShutdown(
+  child: ChildProcess,
+  controlToken: string | null,
+  timeout = GRACEFUL_SHUTDOWN_TIMEOUT_MS,
+): Promise<boolean> {
+  if (child.exitCode !== null) return Promise.resolve(true);
+  const stdin = child.stdin;
+  if (!controlToken || !stdin?.writable) return Promise.resolve(false);
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (stopped: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.off("exit", onExit);
+      child.off("close", onExit);
+      resolve(stopped);
+    };
+    const onExit = () => finish(true);
+    const timer = setTimeout(() => finish(false), timeout);
+
+    child.once("exit", onExit);
+    child.once("close", onExit);
+    stdin.write(`shutdown:${controlToken}\n`, (error) => {
+      if (error) finish(false);
+    });
+  });
+}
+
+async function stopPythonProcess(
+  child: ChildProcess,
+  controlToken: string | null,
+): Promise<void> {
+  const stoppedGracefully = await requestGracefulShutdown(child, controlToken);
+  if (stoppedGracefully) return;
+
+  console.warn(
+    "Warning: Python server did not stop gracefully; forcing process termination.",
+  );
+  await killProcessTree(child);
+}
+
 function spawnPython(port: number, browserSyncPort?: number): ChildProcess {
   const pythonPath = getVenvPythonPath();
   const args = ["-u", "main.py"];
 
   console.log(`-> Starting Python server on port ${port}...`);
 
+  pythonControlToken = randomBytes(32).toString("hex");
   const env = {
     ...process.env,
     PYTHONUNBUFFERED: "1",
     PORT: String(port),
+    CASPIAN_DEV_CONTROL_TOKEN: pythonControlToken,
     ...(browserSyncPort
       ? { CASPIAN_BROWSER_SYNC_PORT: String(browserSyncPort) }
       : {}),
   };
 
   const child = spawn(pythonPath, args, {
-    stdio: "inherit",
+    stdio: ["pipe", "inherit", "inherit"],
     shell: false,
     detached: !isWindows(),
     env,
@@ -158,10 +206,12 @@ export async function restartPythonServer(
   try {
     console.log("-> Restarting Python server...");
     const prev = pythonProcess;
+    const prevControlToken = pythonControlToken;
     pythonProcess = null;
+    pythonControlToken = null;
 
     if (prev) {
-      await killProcessTree(prev);
+      await stopPythonProcess(prev, prevControlToken);
       await waitForPortRelease(port);
     }
 
@@ -171,10 +221,12 @@ export async function restartPythonServer(
   }
 }
 
-export function stopPythonServer(): void {
+export async function stopPythonServer(): Promise<void> {
   const prev = pythonProcess;
+  const prevControlToken = pythonControlToken;
   pythonProcess = null;
-  if (prev) killProcessTree(prev);
+  pythonControlToken = null;
+  if (prev) await stopPythonProcess(prev, prevControlToken);
 }
 
 export async function waitForHttpHealth(

package/dist/tests/test_main_helpers.py

@@ -1,13 +1,76 @@
-"""Unit tests for the pure helper functions in `main.py`.
+"""Unit tests for focused helper and lifecycle functions in `main.py`.
 
 These cover the app-owned logic that has no external dependencies: env
 parsing, query-param coercion, and the component-deferral HTML transform.
 """
 
 import inspect
+import io
+from dataclasses import replace
+from types import SimpleNamespace
 from typing import Optional
+from unittest.mock import AsyncMock
 
 import main
+from conftest import run_async
+
+
+class TestPrismaLifespan:
+    def test_disconnects_on_shutdown(self, monkeypatch):
+        disconnect = AsyncMock()
+        monkeypatch.setattr(main.prisma, "disconnect", disconnect)
+
+        async def exercise_lifespan():
+            async with main.prisma_lifespan(main.app):
+                disconnect.assert_not_awaited()
+
+        run_async(exercise_lifespan())
+        disconnect.assert_awaited_once_with()
+
+    def test_disabled_prisma_is_not_registered(self, monkeypatch):
+        monkeypatch.setattr(main, "cfg", replace(main.cfg, prisma=False))
+
+        assert main.prisma_lifespan not in main.get_app_lifespans()
+
+    def test_disconnects_when_another_lifespan_raises(self, monkeypatch):
+        disconnect = AsyncMock()
+        monkeypatch.setattr(main.prisma, "disconnect", disconnect)
+
+        async def exercise_lifespan():
+            try:
+                async with main.prisma_lifespan(main.app):
+                    raise RuntimeError("shutdown path")
+            except RuntimeError:
+                pass
+
+        run_async(exercise_lifespan())
+        disconnect.assert_awaited_once_with()
+
+
+class TestDevControlPipe:
+    def test_valid_shutdown_command_stops_server(self):
+        server = SimpleNamespace(should_exit=False)
+
+        main._consume_dev_control_stream(
+            server,
+            "expected-token",
+            io.StringIO("shutdown:expected-token\n"),
+        )
+
+        assert server.should_exit is True
+
+    def test_ignores_invalid_commands_until_pipe_closes(self):
+        server = SimpleNamespace(should_exit=False)
+
+        main._consume_dev_control_stream(
+            server,
+            "expected-token",
+            io.StringIO("shutdown:wrong-token\nnoop:expected-token\n"),
+        )
+
+        # EOF means the owning development orchestrator exited, so an otherwise
+        # orphaned child still shuts down cleanly.
+        assert server.should_exit is True
 
 
 class TestEnvParsing:

package/package.json

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