caspian-utils 0.0.1

package/dist/docs/database.md

@@ -0,0 +1,351 @@
+---
+title: Database
+description: Use Prisma in Caspian with the generated async Python client, schema-first workflow, and the shared imports under `src/lib/prisma/`.
+related:
+  title: Related docs
+  description: Use the project structure guide to place database files correctly, then use the fetch-data guide when Prisma calls need to power route rendering or RPC actions.
+  links:
+    - /docs/commands
+    - /docs/project-structure
+    - /docs/fetch-data
+    - /docs/validation
+    - /docs/index
+---
+
+This page documents the default Caspian database workflow with Prisma ORM.
+
+Treat Prisma as the default persistence layer when a Caspian app includes database support. The Prisma schema is the source of truth, the generated Python client is the runtime interface, and route code should import the shared client from `src.lib.prisma` instead of constructing ad hoc database connections inside each page or RPC action.
+
+## Overview
+
+The standard Prisma flow in Caspian is:
+
+1. Define models in `prisma/schema.prisma`.
+2. Configure `DATABASE_URL` in `.env`.
+3. Run `npx ppy generate` after schema changes.
+4. Import the generated async client from `src.lib.prisma.db` or `src.lib.prisma`.
+5. Use Prisma calls inside `page()`, `layout()`, or `@rpc()` actions.
+
+Use this workflow instead of writing raw SQL first. Drop to raw SQL only when a query cannot be expressed clearly with the generated client.
+
+## Environment Setup
+
+Add your database connection string to `.env`.
+
+Example for SQLite in development:
+
+```env
+DATABASE_URL="file:./prisma/dev.db"
+```
+
+Example for PostgreSQL in async-friendly production environments:
+
+```env
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
+```
+
+For most local development, SQLite is the simplest starting point. For production or higher concurrency workloads, prefer PostgreSQL or MySQL.
+
+## Global Prisma Configuration
+
+Use `prisma.config.ts` for seed configuration and ORM-level behavior.
+
+Example:
+
+```ts
+export default {
+  seed: {
+    import: "./prisma/seed.ts",
+    autoRun: true,
+  },
+  client: {
+    logLevel: "info",
+  },
+}
+```
+
+Keep schema in `prisma/schema.prisma`, connection secrets in `.env`, and generation or seed behavior in `prisma.config.ts`.
+
+## Define Your Schema
+
+Model your data in `prisma/schema.prisma`. This file is the source of truth for both the database structure and the generated Python client API.
+
+Example:
+
+```prisma
+datasource db {
+  provider = "sqlite"
+  url      = env("DATABASE_URL")
+}
+
+generator client {
+  provider = "prisma-client-py"
+}
+
+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)
+  authorId  String
+  author    User     @relation(fields: [authorId], references: [id])
+}
+```
+
+After changing the schema, regenerate the Python client before using new models or fields in app code.
+
+## Command Reference
+
+Use these commands for the normal Prisma lifecycle in Caspian:
+
+- `npx ppy generate` compiles `schema.prisma` into the generated Python client. Run this after every schema change.
+- `npx prisma migrate dev` creates and applies a development migration.
+- `npx prisma migrate deploy` applies pending migrations in deployment environments.
+- `npx prisma db push` syncs schema changes without creating a migration file, which is useful for prototyping.
+- `npx prisma db seed` runs the configured seeding script.
+- `npx prisma studio` opens the Prisma data browser.
+
+Default rule:
+
+- Use `npx ppy generate` every time the schema changes.
+- Use migrations for tracked application changes.
+- Use `db push` only when you intentionally want a faster, migration-free prototype loop.
+
+## Generated Python Client Files
+
+In a Prisma-enabled Caspian app, the generated and shared Python imports live under `src/lib/prisma/`.
+
+### `src/lib/prisma/db.py`
+
+This module exposes the shared Prisma client instance used by route code and RPC actions.
+
+Typical usage:
+
+```python
+from src.lib.prisma.db import prisma
+
+users = await prisma.user.find_many()
+```
+
+Use this import as the default way to access the database. Do not instantiate new Prisma clients inside each request handler unless you are solving a very specific lifecycle problem.
+
+### `src/lib/prisma/models.py`
+
+This module contains the generated Python model types derived from `prisma/schema.prisma`.
+
+Use it when you need explicit model imports for typing, serialization, or helper code that works with generated record objects.
+
+Typical usage pattern:
+
+```python
+from src.lib.prisma import models
+
+def as_public_user(user: models.User) -> dict:
+    return {
+        "id": user.id,
+        "email": user.email,
+        "name": user.name,
+    }
+```
+
+Treat these classes as generated artifacts. Change the schema, then regenerate, instead of editing model definitions by hand.
+
+### `src/lib/prisma/__init__.py`
+
+This module is the package entry point for Prisma imports.
+
+If it re-exports the shared client and generated model helpers, application code can use a shorter import shape such as:
+
+```python
+from src.lib.prisma import prisma, models
+```
+
+Prefer this package-level import when it keeps route code clearer. Prefer direct imports from `db.py` when you want to make the client source explicit.
+
+## Async Client Usage
+
+The Prisma client in Caspian should be treated as async-first. Use `await` for database operations.
+
+Example:
+
+```python
+from src.lib.prisma.db import prisma
+
+async def page():
+    users = await prisma.user.find_many()
+
+    return {
+        "users": [user.to_dict() for user in users],
+    }
+```
+
+Prisma calls fit naturally in:
+
+- `async def page()` for first-render data
+- `async def layout()` for shared section data
+- `@rpc()` actions for browser-triggered reads and writes
+
+See `fetch-data.md` for the recommended route-render versus RPC split.
+
+## CRUD Examples
+
+### Create
+
+```python
+user = await prisma.user.create(
+    data={
+        "email": "alice@example.com",
+        "name": "Alice",
+    }
+)
+```
+
+### Read
+
+Filtering and sorting:
+
+```python
+posts = await prisma.post.find_many(
+    where={
+        "published": True,
+        "title": {"contains": "Caspian"},
+    },
+    order_by={
+        "title": "asc",
+    },
+)
+```
+
+Selection and relations:
+
+```python
+user = await prisma.user.find_unique(
+    where={"email": "alice@example.com"},
+    include={"posts": True},
+)
+```
+
+### Update
+
+```python
+updated_user = await prisma.user.update(
+    where={"id": "123"},
+    data={
+        "name": "New Name",
+    },
+)
+```
+
+If your schema includes numeric counters, Prisma also supports atomic update operators such as `increment` and `decrement`.
+
+### Delete
+
+```python
+await prisma.user.delete(where={"id": "123"})
+
+await prisma.post.delete_many(
+    where={
+        "published": False,
+    }
+)
+```
+
+## Using Prisma In RPC Actions
+
+Prisma is a strong fit for Caspian RPC because both are async-friendly.
+
+Example:
+
+```python
+from casp.rpc import rpc
+from casp.validate import Validate
+from src.lib.prisma import prisma
+
+@rpc()
+async def create_user(email: str, name: str | None = None):
+    if Validate.with_rules(email, "required|email") is not True:
+        raise ValueError("A valid email address is required")
+
+    user = await prisma.user.create(
+        data={
+            "email": email,
+            "name": name,
+        }
+    )
+
+    return user.to_dict()
+```
+
+Use validation before writes, especially for form payloads and public RPC actions. See `validation.md` for the recommended boundary checks.
+
+## Advanced Features
+
+### Aggregations
+
+```python
+stats = await prisma.post.aggregate(
+    _count={"_all": True},
+    where={"published": True},
+)
+
+print(stats["_count"]["_all"])
+```
+
+### Transactions
+
+```python
+async with prisma.tx() as tx:
+    user = await tx.user.create(
+        data={
+            "email": "alice@example.com",
+            "name": "Alice",
+        }
+    )
+    await tx.post.create(
+        data={
+            "title": "Welcome post",
+            "authorId": user.id,
+        }
+    )
+```
+
+### Raw SQL Fallback
+
+```python
+users = await prisma.query_raw(
+    "SELECT * FROM User WHERE email LIKE ?",
+    "%@gmail.com",
+)
+```
+
+Use raw SQL sparingly. Prefer the generated Prisma API when the query can be expressed clearly there.
+
+## Recommended Project Rules
+
+- Keep the schema in `prisma/schema.prisma` and regenerate the client after changes.
+- Import the shared client from `src.lib.prisma.db` or `src.lib.prisma`, not from ad hoc connection code scattered across routes.
+- Keep reusable database helpers in `src/lib/`, and keep route-specific orchestration in `src/app/`.
+- Use `await` with Prisma operations.
+- Convert Prisma objects to template-safe dictionaries when rendering HTML.
+- Validate incoming mutation data before calling `create`, `update`, or `delete` operations.
+- Prefer Prisma queries over raw SQL, and prefer raw SQL over undocumented custom query helpers.
+
+## AI Routing Notes
+
+If an AI agent is working on a Caspian app with Prisma enabled, apply these rules first.
+
+- Treat Prisma as the default ORM and persistence layer.
+- Read `prisma/schema.prisma` before proposing model, relation, or field changes.
+- Run `npx ppy generate` after schema changes so the Python client matches the schema.
+- Import the shared client from `src.lib.prisma.db` or the `src.lib.prisma` package entry point.
+- Treat `src/lib/prisma/models.py` as generated model output, not hand-authored business logic.
+- Put reusable database helpers in `src/lib/`; keep route and RPC orchestration in `src/app/`.
+- Use `page()` or `layout()` for first-render reads and `@rpc()` plus `pp.rpc()` for browser-triggered reads and writes.
+- Check `fetch-data.md` for route versus RPC guidance and `validation.md` before writing public mutations.

package/dist/docs/fetch-data.md

@@ -0,0 +1,260 @@
+---
+title: Fetch Data
+description: Fetch first-render and interactive data in Caspian with async route functions, `@rpc()` actions, `pp.rpc()`, streaming, and uploads, with RPC as the default browser-to-server data path.
+related:
+  title: Related docs
+  description: Use the routing guide to place route logic correctly, then use the auth guide for protected actions, the state guide for transient request-scoped mutation state, the cache guide for reusable first-render HTML, and the PulsePoint runtime guide for client-side `pp.rpc()` details.
+  links:
+    - /docs/auth
+    - /docs/state
+    - /docs/database
+    - /docs/cache
+    - /docs/routing
+    - /docs/pulsepoint
+    - /docs/project-structure
+    - /docs/index
+---
+
+This page explains how data fetching works in Caspian. Use route functions for initial page data and use RPC actions for browser-triggered reads, writes, streams, and uploads.
+
+Treat RPC as the default way for browser code to talk to Python in Caspian. Do not reach for ad hoc fetch calls to custom JSON endpoints, alternate transport layers, or older helper names unless the task explicitly requires that shape.
+
+## Overview
+
+Caspian has two main data-loading paths:
+
+- `page()` or `layout()` for server-side data needed during the initial render
+- `@rpc()` plus `pp.rpc()` for interactive fetches after the page is already loaded
+
+In practice, most pages use both:
+
+1. Load the first screen of data in `index.py`.
+2. Render that data into `index.html`.
+3. Call `pp.rpc()` for refreshes, form submits, toggles, infinite scroll, or streamed updates.
+
+## Default Data Rule
+
+- Use `page()` or `layout()` for data required before HTML renders.
+- Use `@rpc()` on the server and `pp.rpc()` in PulsePoint code for all browser-triggered data work after first render.
+- Keep custom REST or other endpoint patterns as explicit exceptions, not the baseline Caspian approach.
+
+## Initial Data In `index.py`
+
+Use the route's backend file for data that should exist before the template is rendered.
+
+Example:
+
+```python
+from casp.layout import render_page
+from src.lib.prisma import prisma
+
+async def page():
+    todos = await prisma.todo.find_many()
+
+    return render_page(__file__, {
+        "todos": [todo.to_dict() for todo in todos],
+    })
+```
+
+Use this pattern for:
+
+- SEO-sensitive page content
+- The first render of lists, dashboards, and detail views
+- Data that layouts or templates need before the browser runs any client code
+
+If a route's first-render HTML is public and stable enough to reuse across requests, pair this pattern with [cache.md](./cache.md) for route-level page caching and invalidation guidance.
+
+Notes:
+
+- Prefer `async def page()` when your database or API client is async-capable.
+- Put shared section-level data in `layout.py` when multiple child routes need the same payload.
+- Keep reusable database or API clients under `src/lib/`; keep route-specific orchestration in `src/app/`.
+
+If the data source is Prisma, see `database.md` for schema, generation, and shared client import conventions.
+
+## Interactive Data With RPC
+
+Use RPC when the browser needs to call Python after the initial page load.
+
+Framework internals note:
+
+- The `@rpc()` decorator and Caspian RPC bridge internals live in `.venv/Lib/site-packages/casp/rpc.py`.
+- Treat that file as framework code. Read it when you need to understand or debug Caspian's RPC behavior, not when you are adding normal app-level actions.
+
+Define a server action with `@rpc()`:
+
+```python
+from casp.rpc import rpc
+from src.lib.prisma import prisma
+
+@rpc()
+async def list_todos():
+    return await prisma.todo.find_many()
+
+@rpc(require_auth=True, limits="20/minute")
+async def create_todo(title: str):
+    return await prisma.todo.create(
+        data={"title": title, "completed": False}
+    )
+```
+
+Call it from the client with `pp.rpc()`:
+
+```html
+<script>
+  async function refreshTodos() {
+    const todos = await pp.rpc("list_todos");
+    console.log(todos);
+  }
+
+  async function addTodo(title) {
+    const todo = await pp.rpc("create_todo", { title });
+    console.log(todo);
+  }
+</script>
+```
+
+Use RPC for:
+
+- Button-triggered refreshes
+- Form submissions and mutations
+- Polling or background refreshes
+- Filters, sorting, and pagination
+- Any browser-to-server interaction that should not require a full page navigation
+
+Validate incoming form and mutation payloads before persisting them. See [validation.md](./validation.md).
+
+If an RPC action needs transient request-scoped success or error state beyond its direct return payload, read [state.md](./state.md) and verify the current wire-request lifecycle before depending on persistence across navigations or full-page reloads.
+
+Important:
+
+- `pp.rpc()` posts to the current route RPC bridge.
+- Older docs may refer to `pp.fetchFunction()`. In this repo's current runtime, the supported helper is `pp.rpc()`.
+
+## Streaming Responses
+
+Caspian RPC supports streaming via Server-Sent Events when the action yields values.
+
+Example:
+
+```python
+from casp.rpc import rpc
+import asyncio
+
+@rpc(limits="10/minute")
+async def stream_summary(prompt: str):
+    response = f"Streaming a summary for: {prompt}"
+
+    for word in response.split():
+        yield word + " "
+        await asyncio.sleep(0.1)
+```
+
+Client example:
+
+```html
+<script>
+  async function runStream(prompt) {
+    await pp.rpc("stream_summary", { prompt }, {
+      onStream: (chunk) => {
+        console.log("chunk", chunk);
+      },
+      onStreamComplete: () => {
+        console.log("stream complete");
+      },
+    });
+  }
+</script>
+```
+
+Use streaming when the user should see partial progress instead of waiting for a single final payload.
+
+## File Uploads
+
+RPC actions can accept FastAPI upload types.
+
+Example:
+
+```python
+from fastapi import File, UploadFile
+from casp.rpc import rpc
+import shutil
+
+@rpc()
+def upload_file(file: UploadFile = File(...)):
+    with open(f"uploads/{file.filename}", "wb") as buffer:
+        shutil.copyfileobj(file.file, buffer)
+
+    return {
+        "status": "success",
+        "filename": file.filename,
+        "size": file.size,
+    }
+```
+
+On the client, call `pp.rpc()` and pass `onUploadProgress` when the UI needs progress updates.
+
+## Auth, Roles, And Limits
+
+The `@rpc()` decorator also controls access and abuse protection.
+
+Example:
+
+```python
+from casp.rpc import rpc
+
+@rpc(
+    require_auth=True,
+    allowed_roles=["admin"],
+    limits="5/minute",
+)
+def delete_user(user_id: int):
+    return {"deleted": user_id}
+```
+
+Use these options for privileged reads, destructive mutations, and endpoints that could be abused if left unbounded.
+
+Use [auth.md](./auth.md) when the action should also participate in centralized session config, page decorators, guest-only flows, RBAC route policy, or OAuth provider handling.
+
+According to the upstream Caspian RPC docs, actions are private by default until decorated with `@rpc()`, and the framework includes CSRF protection plus origin validation for exposed actions.
+
+## Serialization Rules
+
+For RPC responses, Caspian can automatically serialize common Python return types such as:
+
+- dictionaries and lists
+- Pydantic models
+- dataclasses
+- Prisma objects
+
+For initial route rendering with `render_page(...)`, prefer passing plain template-ready dictionaries or lists so the HTML layer gets explicit data shapes.
+
+## Recommended Decision Rule
+
+Use `page()` or `layout()` when the data is part of the page render. Use `@rpc()` plus `pp.rpc()` when the browser needs to ask the server for more data after the page is already visible.
+
+A common pattern is:
+
+- Fetch the first page of data in `index.py`
+- Render that data into the HTML template
+- Use RPC for subsequent filters, mutations, refreshes, streaming, or uploads
+
+If the first-render HTML is expensive to produce and safe to share between visitors, add route-level caching with [cache.md](./cache.md) and invalidate affected URIs after successful mutations.
+
+## AI Routing Notes
+
+If an AI agent is choosing how to load data in Caspian, apply these rules first.
+
+- Put first-render data loading in `src/app/**/index.py`.
+- Put shared section data in `layout.py` when multiple child routes need it.
+- Treat RPC as the default read and write layer between PulsePoint code and Python route logic.
+- Use `@rpc()` for backend functions that should be callable from the browser.
+- Use `pp.rpc()` for client-side calls; do not prefer older `pp.fetchFunction()` wording.
+- Prefer route-render data plus RPC over inventing parallel REST endpoints for normal Caspian page interactions.
+- Use [cache.md](./cache.md) when a route's initial HTML should be reused across requests and invalidated after writes.
+- Use [state.md](./state.md) when an RPC mutation needs transient request-scoped success or error state outside the direct response payload.
+- Use `onStream` for streamed responses and `onUploadProgress` for upload-aware client calls.
+- Add `require_auth`, `allowed_roles`, and `limits` to sensitive RPC actions.
+- Keep reusable database clients and service wrappers in `src/lib/`.
+- Use `.venv/Lib/site-packages/casp/rpc.py` only when the task is about Caspian core RPC internals or framework debugging.
+- Check [routing.md](./routing.md) before adding new route files and [pulsepoint.md](./pulsepoint.md) before generating raw client runtime code.

package/dist/docs/index.md

@@ -0,0 +1,65 @@
+---
+title: Caspian Docs
+description: Caspian documentation with AI-aware routing to the right local docs before framework-specific code generation or project setup changes, with PulsePoint, RPC, and Validate as the default app stack.
+related:
+  title: Next Steps
+  description: Start with installation, review the CLI commands, then use the structure guide to place Caspian files correctly.
+  links:
+    - /docs/installation
+    - /docs/commands
+    - /docs/project-structure
+---
+
+This directory contains the local Caspian documentation set for quick reference and AI-aware routing.
+
+## Default Stack
+
+When generating or editing a Caspian app, treat these as the default choices unless the task explicitly requires something else:
+
+- Use PulsePoint for reactive frontend behavior.
+- Use `@rpc()` plus `pp.rpc()` for browser-triggered reads, writes, streaming, and uploads.
+- Use `Validate` and `Rule` from `casp.validate` for server-side input validation and sanitization.
+
+## Docs Location
+
+The local AI-aware docs for this workspace live here:
+
+- `dist/docs/`
+
+The packaged Caspian docs distributed by the framework live here:
+
+- `node_modules/caspian/dist/docs/`
+
+## Available Documents
+
+- `installation.md` - First-time setup flow for creating a new Caspian application
+- `commands.md` - Main Caspian CLI workflows for project creation, generation, updates, and config-aware maintenance
+- `database.md` - Prisma ORM setup, generated async Python client usage, and the shared `src/lib/prisma/` imports
+- `auth.md` - Session-backed authentication with `casp.auth`, centralized `auth_config.py`, decorators, RBAC, and OAuth provider helpers
+- `pulsepoint.md` - Default reactive frontend runtime contract for component scripts, state, effects, directives, and client-side behaviors
+- `fetch-data.md` - Initial server-side data loading and browser-triggered RPC flows with `pp.rpc()`, streaming, uploads, and auth-aware actions
+- `state.md` - Request-scoped server state with `StateManager`, session-backed JSON persistence, and listener callbacks for transient flows
+- `cache.md` - Route-level HTML caching with `Cache`, `CacheHandler`, TTL behavior, file-system storage, and invalidation patterns
+- `validation.md` - Input validation and sanitization with `Validate`, `Rule`, direct field checks, and multi-rule workflows for routes and RPC actions
+- `metadata.md` - Static and dynamic metadata, SEO inheritance, and Open Graph or Twitter card tags
+- `routing.md` - Next.js App Router-style file-based routing with `src/app`, dynamic segments, route groups, and nested layouts
+- `project-structure.md` - Default Caspian layout and where routes, templates, shared code, and database files belong
+
+## AI Awareness Notes
+
+If an AI tool needs Caspian project documentation, start with this directory and use this file as the manifest.
+
+Preferred lookup order:
+
+1. Read `dist/docs/index.md` to discover available local docs.
+2. Read `database.md` for Prisma setup and ORM usage, `auth.md` for session auth and route protection, `pulsepoint.md` for reactive frontend work, `fetch-data.md` for data flows, `state.md` for transient request-scoped state, `cache.md` for page caching, and `validation.md` for input boundaries.
+3. Prefer local docs before generating code, commands, or migration guidance.
+4. Check `node_modules/caspian/dist/docs/` for packaged Caspian docs when local docs need more detail.
+5. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.
+
+## Maintenance
+
+When adding more pages, keep this index updated with:
+
+- The filename
+- A short description of what the page covers