create-caspian-app 0.2.0-beta.9 → 0.2.0-beta.90

package/README.md

@@ -1,70 +1,114 @@
 # Caspian — The Native Python Web Framework for the Reactive Web
 
-Caspian is a high‑performance, **FastAPI-powered** full‑stack framework that brings **reactive UI** to Python without forcing a JavaScript backend. It combines:
+Caspian is a high-performance, FastAPI-powered full-stack framework that brings reactive UI to Python without forcing a JavaScript backend. It combines:
 
 - **FastAPI Engine** for async-native performance and the broader FastAPI ecosystem
-- A **Hybrid Frontend Engine**: start with zero-build HTML, then upgrade to **Vite + NPM + TypeScript** when needed
-- **Direct async RPC** (“Zero‑API”): call Python functions from the browser via `pp.rpc()`
-- **File‑system routing** with nested layouts and dynamic routes
+- **Hybrid Frontend Engine**: start with zero-build HTML, then upgrade to Vite + NPM + TypeScript when needed
+- **Direct async RPC** ("Zero-API"): call Python functions from the browser via `pp.rpc()`
+- **File-system routing** with nested layouts and dynamic routes (Next.js App Router mental model)
 - **Prisma ORM integration** with an auto-generated, type-safe Python client
-- A secure, session-based **auth system** and built-in security defaults
+- **PulsePoint** — a lightweight browser-side reactive runtime for interactive UI
+- **Session-based authentication** with RBAC support and built-in security defaults
 
 ---
 
 ## Quick Start
 
-### 1) Requirements
+### Requirements
 
-- **Node.js**: v22.13.0+
+- **Node.js**: v24.13.1+
 - **Python**: v3.14.0+
 
-### 2) Create an app (interactive wizard)
+### Create an app (interactive wizard)
 
 ```bash
 npx create-caspian-app@latest
 ```
 
-Example prompts you’ll see in the wizard:
+The wizard walks through the main project options:
 
 - Project name
-- Tailwind CSS
-- Prisma ORM
-- Backend only (no frontend assets)
-- TypeScript support
+- Feature toggles: backend-only mode, Tailwind CSS, Prisma, MCP, TypeScript
+- Starter kit selection (basic, fullstack, api, realtime)
 
-### 3) Run dev server
+### Run dev server
 
 ```bash
 cd my-app
 npm run dev
 ```
 
+> **Note:** Many Caspian projects use BrowserSync plus PostCSS watchers rather than a Vite dev server. Check `package.json` for the actual dev script.
+
 ---
 
-## What “Reactive Python” looks like
+## What "Reactive Python" looks like
+
+A Caspian page is plain HTML with reactive directives plus a small `<script>` block for state. The framework handles the rest.
 
-A Caspian page can be plain HTML with reactive directives, plus a small `<script>` block for state.
+### Route template (`src/app/todos/index.html`)
 
 ```html
-<!-- src/app/todos/index.html -->
+<!-- @import { Badge } from "../components/ui" -->
+
+<section>
+  <div class="flex gap-2 mb-4">
+    <x-badge variant="default">Tasks: {todos.length}</x-badge>
+  </div>
+
+  <ul>
+    <template pp-for="(todo, index) in todos">
+      <li key="{todo.id}" class="p-2 border-b">
+        {index + 1}. {todo.title}
+        <button onclick="removeTodo(todo.id)">Remove</button>
+      </li>
+    </template>
+  </ul>
+
+  <script>
+    const [todos, setTodos] = pp.state([]);
+    function removeTodo(id) {
+      setTodos(todos.filter((todo) => todo.id !== id));
+    }
+  </script>
+</section>
+```
 
-<!-- Import Python Components -->
-<!-- @import { Badge } from ../components/ui -->
+### Backend RPC (`src/app/todos/index.py`)
 
-<div class="flex gap-2 mb-4">
-  <Badge variant="default">Tasks: {todos.length}</Badge>
-</div>
+```python
+from casp.rpc import rpc
+from casp.validate import Validate
+from src.lib.prisma.db import prisma
+
+@rpc()
+async def create_todo(title):
+    if Validate.with_rules(title, "required|min:3") is not True:
+        raise ValueError("Title must be at least 3 chars")
+
+    new_todo = await prisma.todo.create(data={
+        "title": title,
+        "completed": False
+    })
+    return new_todo.to_dict()
 
-<!-- Reactive Loop -->
-<ul>
-  <template pp-for="todo in todos">
-    <li key="{todo.id}" class="p-2 border-b">{todo.title}</li>
-  </template>
-</ul>
+@rpc(require_auth=True)
+async def delete_todo(id, _current_user_id=None):
+    await prisma.todo.delete(where={"id": id})
+    return {"success": True}
+```
+
+### Frontend call
 
+```html
 <script>
-  // State initialized by Python backend automatically
-  const [todos, setTodos] = pp.state([[todos]]);
+  async function add(e) {
+    e.preventDefault();
+    const data = Object.fromEntries(new FormData(e.target));
+    const newTodo = await pp.rpc("create_todo", data);
+    setTodos([newTodo, ...todos]);
+    e.target.reset();
+  }
 </script>
 ```
 
@@ -74,37 +118,31 @@ A Caspian page can be plain HTML with reactive directives, plus a small `<script
 
 ### FastAPI engine, async-native
 
-Your logic runs in native async Python and can leverage FastAPI/Starlette features (DI, middleware, validation, etc.) without a separate JS backend.
+Your logic runs in native async Python and can leverage FastAPI/Starlette features (dependency injection, middleware, validation, etc.) without a separate JS backend.
 
 ### Hybrid frontend engine (zero-build → Vite)
 
 Start with simple HTML-first development for speed and clarity, then adopt Vite + NPM + TypeScript when you need richer libraries or complex bundles.
 
-### “Zero‑API” server actions (RPC)
+### "Zero-API" server actions (RPC)
 
-Define `async def` actions and call them directly from the browser; Caspian handles serialization, security, and async execution.
+Define `async def` actions decorated with `@rpc()` and call them directly from the browser; Caspian handles serialization, security, and async execution via `pp.rpc()`.
 
-### File‑system routing with nested layouts
+### File-system routing with nested layouts
 
 Routes are determined by files in `src/app`, supporting dynamic segments (`[id]`), catch-alls (`[...slug]`), route groups (`(auth)`), and layout nesting via `layout.html`.
 
 ### Prisma ORM integration (type-safe Python client)
 
-Define a single Prisma schema and generate a typed Python client—autocomplete-first database access without boilerplate.
+Define a single Prisma schema and generate a typed Python client — autocomplete-first database access without boilerplate.
 
-### Security defaults and authentication
+### PulsePoint reactive runtime
 
-Built-in CSRF protection, strict Origin validation, HttpOnly cookies, and a session-based auth model with RBAC support.
+A lightweight browser-side reactive runtime ships with Caspian. It follows a React-like mental model but is HTML-first rather than JSX-first, with `pp.state`, `pp.effect`, `pp.ref`, `pp-context`, `pp-for`, and `pp.portal`.
 
----
-
-## Installation & DX setup (VS Code)
-
-For the best developer experience, Caspian’s docs recommend:
+### Security defaults and authentication
 
-- **Caspian Official Framework Support** (component autocompletion + snippets)
-- **Prisma** schema formatting/highlighting
-- **Tailwind CSS** IntelliSense & class sorting
+Built-in CSRF protection, strict Origin validation, HttpOnly cookies, and a session-based auth model with OAuth provider support.
 
 ---
 
@@ -112,31 +150,31 @@ For the best developer experience, Caspian’s docs recommend:
 
 ### Routing
 
-Caspian uses **file-system routing** under `src/app`:
+Caspian follows the same mental model as the Next.js App Router. Your directory structure becomes your URL structure.
 
-| File Path                       | URL Path      |
+| File                            | URL           |
 | ------------------------------- | ------------- |
 | `src/app/index.html`            | `/`           |
-| `src/app/about/index.py`        | `/about`      |
+| `src/app/about/index.html`      | `/about`      |
 | `src/app/blog/posts/index.html` | `/blog/posts` |
 
 #### Dynamic segments
 
-```txt
-src/app/users/[id]/index.py   ->  /users/123
+```
+src/app/users/[id]/index.html   ->  /users/123
 ```
 
 #### Catch-all segments
 
-```txt
-src/app/docs/[...slug]/index.py   ->  /docs/getting-started/setup
+```
+src/app/docs/[...slug]/index.html   ->  /docs/getting-started/setup
 ```
 
 #### Route groups (organize without changing URLs)
 
-```txt
-src/app/(auth)/login/index.py     ->  /login
-src/app/(auth)/register/index.py  ->  /register
+```
+src/app/(auth)/login/index.html     ->  /login
+src/app/(auth)/register/index.html  ->  /register
 ```
 
 #### Nested layouts
@@ -144,241 +182,205 @@ src/app/(auth)/register/index.py  ->  /register
 Layouts wrap pages and preserve state during navigation:
 
 - Root: `src/app/layout.html`
-- Nested: e.g., `/dashboard/settings` inherits root + dashboard layout automatically
+- Section: e.g., `/dashboard/settings` inherits root + dashboard layout automatically
+
+> **Rule:** For UI routes, keep markup in `index.html` and server logic in `index.py`. For section layouts, keep the visible wrapper in `layout.html` and layout-level props in `layout.py`.
 
 ---
 
 ### Components (Python-first, HTML when you want it)
 
-Components are Python functions decorated with `@component`.
+Components are Python functions decorated with `@component`. Import them with `<!-- @import ... -->` comments and render them with `x-*` tags.
 
-#### Atomic component (best for buttons, badges, icons, etc.)
+#### Atomic component
 
-```py
-from casp.html_attrs import get_attributes, merge_classes
+```python
 from casp.component_decorator import component
+from casp.html_attrs import get_attributes, merge_classes
 
 @component
-def Container(**props):
+def Container(children: str = "", **props) -> str:
     incoming_class = props.pop("class", "")
     final_class = merge_classes("mx-auto max-w-7xl px-4", incoming_class)
-
-    children = props.pop("children", "")
-
     attributes = get_attributes({"class": final_class}, props)
     return f'<div {attributes}>{children}</div>'
 ```
 
-**DX speed tip:** the VS Code extension can generate boilerplate via a snippet like `caspcom`.
+#### Type-safe props
 
-#### Type-safe props (TypeScript-like autocomplete)
-
-```py
-from typing import Literal, Any
+```python
+from typing import Any, Literal
 from casp.component_decorator import component
+from casp.html_attrs import get_attributes, merge_classes
 
-ButtonVariant = Literal["default", "destructive", "outline"]
-ButtonSize = Literal["default", "sm", "lg"]
+ButtonVariant = Literal["default", "outline", "destructive"]
 
 @component
-def Button(
-    children: Any = "",
-    variant: ButtonVariant = "default",
-    size: ButtonSize = "default",
-    **props,
-) -> str:
-    # merge classes + attrs here
-    return f"<button>...</button>"
+def Button(children: Any = "", variant: ButtonVariant = "default", **props) -> str:
+    incoming_class = props.pop("class", "")
+    attrs = get_attributes({
+        "class": merge_classes(f"btn btn-{variant}", incoming_class),
+    }, props)
+    return f'<button {attrs}>{children}</button>'
 ```
 
-**HTML templates for complex UI**
-For larger layouts or reactive UIs, bridge to an HTML file:
+#### Template-backed components (when UI is richer)
+
+`Counter.py`:
 
-```py
+```python
 from casp.component_decorator import component, render_html
 
 @component
-def Counter(**props):
-    return render_html("Counter.html", **props)
-```
-
----
-
-### Reactivity (PulsePoint)
-
-Caspian is built on **PulsePoint**, a lightweight reactive DOM engine, plus Caspian-specific helpers for full-stack workflows.
-
-Core directives/primitives include:
-
-- `pp-component`, `pp-spread`, `pp-ref`, `pp-for`, `pp.state`, `pp.effect`, `pp.ref`, `pp-ignore`
-
-#### `pp.rpc(functionName, data?)`
-
-The bridge to your Python backend. Caspian handles:
-
-- smart serialization (JSON ↔ FormData when `File` is present)
-- auto-redirects when server returns redirect headers
-- `X-CSRF-Token` injection for security
-
-#### `searchParams`
-
-A reactive wrapper around `URLSearchParams` that updates the URL without full reloads.
-
-#### Navigation
-
-Caspian intercepts internal `<a>` links for client-side navigation; for programmatic navigation use:
-
-```js
-pp.redirect("/dashboard");
-```
-
----
-
-## Backend: Async Server Actions (RPC)
-
-Decorate `async def` functions with `@rpc`, then call them from the client using `pp.rpc()`.
-
-**Backend (`src/app/todos/index.py`)**
-
-```py
-from casp.rpc import rpc
-from casp.validate import Validate
-from src.lib.prisma.db import prisma
-
-@rpc()
-async def create_todo(title):
-    if Validate.with_rules(title, "required|min:3") is not True:
-        raise ValueError("Title must be at least 3 chars")
-
-    new_todo = await prisma.todo.create(data={
-        "title": title,
-        "completed": False
-    })
-    return new_todo.to_dict()
-
-@rpc(require_auth=True)
-async def delete_todo(id, _current_user_id=None):
-    await prisma.todo.delete(where={"id": id})
-    return {"success": True}
+def Counter(label: str = "Clicks") -> str:
+    return render_html(__file__, {"label": label})
 ```
 
-**Frontend (`src/app/todos/index.html`)**
+`Counter.html`:
 
 ```html
-<form onsubmit="add(event)">
-  <input name="title" required />
-  <button>Add</button>
-</form>
+<div>
+  <h3>[[ label ]]</h3>
+  <button onclick="setCount(count + 1)">{count}</button>
 
-<script>
-  const [todos, setTodos] = pp.state([]);
-
-  async function add(e) {
-    e.preventDefault();
-    const data = Object.fromEntries(new FormData(e.target));
-
-    const newTodo = await pp.rpc("create_todo", data);
-    setTodos([newTodo, ...todos]);
-    e.target.reset();
-  }
-</script>
+  <script>
+    const [count, setCount] = pp.state(0);
+  </script>
+</div>
 ```
 
 ---
 
-## Database: Prisma ORM
+### PulsePoint reactivity
 
-Caspian uses a Prisma schema as the single source of truth and generates a typed Python client. It is designed to translate Prisma syntax into optimized SQL without requiring the heavy Prisma Engine binary.
+PulsePoint is the default reactive frontend layer for Caspian. Key APIs:
 
-**Schema (`prisma/schema.prisma`)**
+| API                                | Description                                 |
+| ---------------------------------- | ------------------------------------------- |
+| `pp.state(initial)`                | Returns `[value, setValue]`                 |
+| `pp.effect(callback, deps?)`       | Runs after render; returns cleanup function |
+| `pp.layoutEffect(callback, deps?)` | Runs synchronously after DOM mutation       |
+| `pp.ref(initialValue?)`            | Returns `{ current }`                       |
+| `pp.createContext(defaultValue)`   | Creates a context token                     |
+| `<Context.Provider value="{...}">` | Provide context to descendants              |
+| `pp.context(token)`                | Read context in a descendant                |
+| `pp.portal(ref, target?)`          | Portal rendering to a ref target            |
+| `pp.rpc(name, data?, options?)`    | Call a backend RPC action                   |
+| `pp.redirect(url)`                 | SPA-aware navigation                        |
 
-```prisma
-model User {
-  id        String   @id @default(cuid())
-  email     String   @unique
-  name      String?
-  posts     Post[]
-  createdAt DateTime @default(now())
-}
-
-model Post {
-  id        String   @id @default(cuid())
-  title     String
-  published Boolean  @default(false)
-  author    User     @relation(fields: [authorId], references: [id])
-  authorId  String
-}
-```
-
-### Client usage
-
-```py
-from src.lib.prisma.db import prisma
+#### `pp.rpc(functionName, data?)`
 
-users = prisma.user.find_many()
-```
+The bridge to your Python backend. Caspian handles:
 
-The docs also describe connection pooling and common CRUD patterns (create, find, update, delete), plus aggregations and transactions.
+- Smart serialization (JSON ↔ FormData when `File` is present)
+- CSRF token injection via `X-CSRF-Token`
+- Auto-redirects when server returns redirect headers
+- Upload progress callbacks when `onUploadProgress` is provided
 
 ---
 
-## Authentication (session-based, secure defaults)
+### Authentication (session-based, secure defaults)
 
-Caspian includes session-based authentication with HttpOnly cookies and RBAC-friendly conventions.
+Configure auth in `main.py` and customize settings in `src/lib/auth/auth_config.py`.
 
-**Configure auth in `main.py`**
+| Method                             | Description                   |
+| ---------------------------------- | ----------------------------- |
+| `auth.sign_in(data, redirect_to?)` | Sign in a user                |
+| `auth.sign_out(redirect_to?)`      | Sign out (RPC-first)          |
+| `auth.is_authenticated()`          | Check current session         |
+| `auth.get_payload()`               | Get user payload from session |
 
-- global protection toggle (`is_all_routes_private`)
-- public routes whitelist
-- auth routes (signin/signup)
-- default redirects
+```python
+from casp.auth import Auth, GoogleProvider, GithubProvider, configure_auth
+from src.lib.auth.auth_config import build_auth_settings
 
-The global `auth` object provides:
-
-- `auth.sign_in(data, redirect_to?)`
-- `auth.sign_out(redirect_to?)`
-- `auth.is_authenticated()`
-- `auth.get_payload()`
+configure_auth(build_auth_settings())
+Auth.set_providers(GithubProvider(), GoogleProvider())
+```
 
 ---
 
 ## CLI reference
 
-### Create projects
+### Create a new project
 
 ```bash
-npx create-caspian-app
+npx create-caspian-app my-app
+npx create-caspian-app my-app --starter-kit=fullstack
+npx create-caspian-app my-app --tailwindcss --typescript --prisma
 ```
 
 ### Useful flags
 
-- `--backend-only` skip frontend assets
-- `--tailwindcss` Tailwind CSS v4 + PostCSS + `globals.css`
-- `--typescript` TypeScript support with Vite + `tsconfig.json`
-- `--mcp` Model Context Protocol server scaffolding (AI Agents)
-- `--prisma` Prisma ORM integration + sample schema
+| Flag                  | Description                                    |
+| --------------------- | ---------------------------------------------- |
+| `--backend-only`      | Skip frontend assets                           |
+| `--tailwindcss`       | Enable Tailwind CSS                            |
+| `--prisma`            | Enable Prisma ORM                              |
+| `--mcp`               | Enable MCP server scaffolding                  |
+| `--typescript`        | Enable TypeScript tooling                      |
+| `--starter-kit=<kit>` | Use a preset (basic, fullstack, api, realtime) |
+| `-y`                  | Non-interactive mode                           |
 
-### Code generation
+### Update existing project
+
+```bash
+npx casp update project
+npx casp update project --tag beta
+npx casp update project --version 1.2.3 -y
+```
 
-Generate strict Python data classes (Pydantic) from your Prisma schema:
+### ORM regeneration (after schema changes)
 
 ```bash
+npx prisma migrate dev
+npx prisma generate
+npx prisma db seed
 npx ppy generate
 ```
 
-### Updating the project
+---
+
+## Project structure
 
-```bash
-npx casp update project
 ```
+my-app/
+├── main.py                     # FastAPI entry point
+├── caspian.config.json         # Feature flags
+├── prisma/
+│   ├── schema.prisma
+│   └── seed.ts
+├── src/
+│   ├── app/                    # File-system routes
+│   │   ├── layout.html         # Root layout
+│   │   ├── index.html          # Home page
+│   │   └── users/
+│   │       └── [id]/
+│   │           └── index.html  # /users/:id
+│   ├── components/             # Reusable UI components
+│   │   └── ui/
+│   │       └── Button.py
+│   └── lib/                    # Non-UI helpers
+│       ├── auth/auth_config.py
+│       └── prisma/
+│           └── db.py
+├── public/                     # Static assets
+└── settings/                   # BrowserSync config
+```
+
+### Key conventions
 
-Tip: use `excludeFiles` in `caspian.config.json` to prevent overwrites during updates.
+- **UI routes:** `index.html` for markup, optional `index.py` for backend logic
+- **Section layouts:** `layout.html` for the wrapper, optional `layout.py` for props
+- **Components:** `src/components/` for reusable UI; `src/lib/` for helpers and services
+- **`<!-- @import ... -->`:** Must appear above the single authored root element
+- **Single-root rule:** Every template must have exactly one top-level parent node with any owned `<script>` inside it
 
 ---
 
 ## Built-in icon workflow (ppicons)
 
-Caspian integrates **ppicons** (Lucide-based), offering 1,500+ icons and an instant add command:
+Caspian integrates **ppicons** (Lucide-based), offering 1,500+ icons:
 
 ```bash
 npx ppicons add Rocket
@@ -387,33 +389,31 @@ npx ppicons add Rocket
 Then use in HTML:
 
 ```html
-<!-- @import { Rocket } from ../lib/ppicons -->
-<Rocket class="w-6 h-6 text-primary" />
+<!-- @import { Rocket } from "../lib/ppicons" -->
+<x-rocket class="w-6 h-6 text-primary" />
 ```
 
 ---
 
-## Project structure (generated by the CLI)
+## Recommended VS Code extensions
 
-High-level layout:
+For the best development experience:
 
-- `main.py` — FastAPI app & ASGI entry
-- `caspian.config.json` — project config
-- `prisma/` — schema + seed scripts
-- `src/` — app routes, pages, styles, shared libs
-- `public/` — static assets served directly
+- **Caspian Official Framework Support** — component snippets and autocomplete
+- **Python** — Python language support
+- **Prisma** — Schema formatting and highlighting
+- **Tailwind CSS IntelliSense** — Class completion and sorting
 
 ---
 
-## License
+## Learn more
 
-MIT
+- Documentation: [caspian.tsnc.tech/docs](https://caspian.tsnc.tech/docs)
+- PulsePoint docs: [pulsepoint.tsnc.tech](https://pulsepoint.tsnc.tech)
+- ppicons library: [ppicons.tsnc.tech](https://ppicons.tsnc.tech)
 
 ---
 
-## Learn more
+## License
 
-- Documentation: [Caspian docs](https://caspian.tsnc.tech/docs)
-- Site: [caspian.tsnc.tech](https://caspian.tsnc.tech)
-- PulsePoint docs: [pulsepoint.tsnc.tech](https://pulsepoint.tsnc.tech)
-- ppicons library: [ppicons.tsnc.tech](https://ppicons.tsnc.tech)
+MIT