caspian-utils 0.0.1

package/dist/docs/installation.md

@@ -0,0 +1,98 @@
+---
+title: Installation
+description: Learn how to create a new Caspian application so AI agents use the first-time setup flow instead of assuming an existing project is already in place.
+related:
+  title: Related docs
+  description: Continue with the routing and structure guides after scaffold so the new app follows Caspian conventions.
+  links:
+    - /docs/routing
+    - /docs/project-structure
+    - /docs/index
+---
+
+This page documents the first-time Caspian setup flow for new applications.
+
+## Overview
+
+Caspian provides a CLI that scaffolds a production-ready project with a FastAPI backend and a PulsePoint-based reactive frontend workflow.
+
+## Default App Stack
+
+The scaffolded Caspian baseline is:
+
+- PulsePoint for reactive frontend behavior.
+- `@rpc()` plus `pp.rpc()` for browser-triggered data fetching and mutations.
+- `casp.validate` with `Validate` and `Rule` for input validation and sanitization.
+
+## System Requirements
+
+Install the supported runtimes before creating a project.
+
+- Node.js `v24.14.0` or newer
+- Python `v3.14.0` or newer
+
+You can verify your environment with:
+
+```bash
+node -v
+python -V
+```
+
+## Create a New App
+
+Run the scaffold command:
+
+```bash
+npx create-caspian-app@latest
+```
+
+The interactive wizard walks through the main project options, including:
+
+- Project name
+- Tailwind CSS support
+- Prisma ORM setup
+- Swagger API documentation
+
+## Recommended VS Code Setup
+
+For the best development experience, use these VS Code extensions:
+
+- [Caspian Official Framework Support](https://marketplace.visualstudio.com/items?itemName=JeffersonAbrahamOmier.caspian)
+- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+- [Pyright](https://marketplace.visualstudio.com/items?itemName=ms-pyright.pyright)
+- [Pyrefly](https://marketplace.visualstudio.com/items?itemName=tamasfe.pyrefly)
+- [Prisma](https://marketplace.visualstudio.com/items?itemName=Prisma.prisma)
+- [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
+
+The Caspian extension is the key piece for Python component snippets and autocomplete.
+
+## Start the Development Server
+
+After scaffolding, move into the generated project and start the development server:
+
+```bash
+cd my-app
+npm run dev
+```
+
+## After Setup
+
+Once the project is scaffolded:
+
+- Read `database.md` when the app includes Prisma ORM support or needs database changes.
+- Read `auth.md` before wiring session config, sign-in or signout routes, route guards, or OAuth providers.
+- Read `pulsepoint.md` before generating interactive frontend behavior.
+- Read `fetch-data.md` before adding browser-triggered reads, writes, uploads, or streams.
+- Read `validation.md` before handling forms, auth input, or RPC payloads.
+- Read `routing.md` to learn how `src/app` folders map to URLs.
+- Read `project-structure.md` to place route code, shared libraries, config, and database files in the correct directories.
+
+## AI Routing Notes
+
+If an AI agent is reading this page, treat it as the source for new-project installation steps.
+
+- Use this workflow when the user is creating a Caspian app from scratch.
+- Do not use existing-project migration or update commands unless the project already exists.
+- After scaffold, default to PulsePoint for interactive UI, RPC for browser-to-server data flow, and `casp.validate` for validation.
+- Once the app exists, check [routing.md](./routing.md) before creating or changing routes under `src/app/`.
+- Check [index.md](./index.md) first when deciding which local doc to follow.

package/dist/docs/metadata.md

@@ -0,0 +1,196 @@
+---
+title: Metadata & SEO
+description: Define static and dynamic metadata in Caspian so titles, descriptions, and social cards inherit correctly from layouts to pages.
+related:
+  title: Related docs
+  description: Use the routing guide to place layout.py and index.py files correctly, then use the structure guide when deciding where metadata defaults belong.
+  links:
+    - /docs/routing
+    - /docs/project-structure
+    - /docs/index
+---
+
+This page explains how Caspian handles document metadata, SEO fields, and social sharing tags.
+
+At render time, Caspian resolves metadata through the layout engine and exposes the merged result to templates as `[[ metadata.* ]]`.
+
+## Overview
+
+Caspian uses a cascading metadata model similar to the Next.js App Router. Define defaults high in the tree, then override them closer to the final route.
+
+Use the `Metadata` class from `casp.layout` when you need to set:
+
+- Page titles
+- Meta descriptions
+- Open Graph tags
+- Twitter card tags
+- Other head metadata through the `extra` dictionary
+
+Metadata is typically defined in one of two files:
+
+- `layout.py` for defaults shared by everything below that folder
+- `index.py` for route-specific metadata
+
+The current `Metadata` implementation supports three fields:
+
+- `title`
+- `description`
+- `extra`
+
+## Static Definition
+
+For metadata that does not depend on route params or fetched data, define a module-level `metadata` variable.
+
+Example:
+
+```python
+from casp.layout import Metadata, render_page
+
+metadata = Metadata(
+    title="About Us | My App",
+    description="Learn more about our team and mission.",
+    extra={
+        "og:title": "About Us | My App",
+        "og:description": "Learn more about our team and mission.",
+        "og:image": "/assets/og-about.jpg",
+        "twitter:card": "summary_large_image",
+    },
+)
+
+async def page():
+    return render_page(__file__)
+```
+
+Use static metadata for:
+
+- Marketing pages
+- Docs pages
+- Any route where the SEO copy is fixed at build or authoring time
+
+The explicit `metadata = Metadata(...)` form is the clearest pattern and should be preferred in project code.
+
+Implementation note:
+
+- If you call `Metadata(...)` at module scope without assigning it, the current layout engine auto-registers that instance as the module's `metadata` value.
+- That shortcut works because `Metadata.__post_init__()` inspects the caller frame and writes to module globals.
+- Prefer the explicit assignment anyway so the intent is obvious to readers and tools.
+
+## Dynamic Generation
+
+For metadata that depends on a dynamic segment or fetched content, instantiate `Metadata(...)` inside the route function. Runtime metadata overrides the static defaults inherited from layouts.
+
+Example:
+
+```python
+from casp.layout import Metadata, render_page
+
+async def page(slug: str):
+    product_name = f"Product {slug.capitalize()}"
+
+    Metadata(
+        title=f"{product_name} | Store",
+        description=f"Buy {product_name} at the best price.",
+        extra={
+            "og:title": f"{product_name} | Store",
+            "twitter:title": f"{product_name} | Store",
+        },
+    )
+
+    return render_page(__file__, {"name": product_name})
+```
+
+Set dynamic metadata before calling `render_page(...)` so the route renders with the correct head values.
+
+Inside the same module, runtime `Metadata(...)` overrides matching keys from the module-level static `metadata` object.
+
+## How Inheritance Works
+
+Caspian merges metadata from the root layout down to the final page. Lower levels override higher levels when they define the same field.
+
+Priority order:
+
+1. `src/app/layout.py` sets site-wide defaults.
+2. Nested `layout.py` files override those defaults for a section.
+3. `index.py` metadata or runtime `Metadata(...)` inside the route has the highest priority.
+
+Within a single file, the layout engine applies static metadata first and then applies runtime metadata from `Metadata(...)`, so runtime values win for matching keys.
+
+If a child route overrides only the title, the description and other fields continue to fall through from the nearest parent that defines them.
+
+Example structure:
+
+```text
+src/
+  app/
+    layout.py
+    blog/
+      layout.py
+      [slug]/
+        index.py
+```
+
+Typical result:
+
+- Root layout defines the site-wide title template and default description.
+- Blog layout overrides section-level fields for `/blog/*`.
+- Blog page overrides the final post title and any page-specific social tags.
+
+## Template Access
+
+Resolved metadata is passed into layout rendering as a `metadata` object.
+
+Example:
+
+```html
+<title>[[ metadata.title ]]</title>
+<meta name="description" content="[[ metadata.description ]]" />
+<meta property="og:image" content="[[ metadata['og:image'] ]]" />
+<meta name="twitter:card" content="[[ metadata['twitter:card'] ]]" />
+```
+
+Use bracket access for `extra` keys that contain characters such as `:`.
+
+## Social Cards With `extra`
+
+Use the `extra` dictionary for Open Graph and Twitter card tags.
+
+Common keys include:
+
+- `og:title`
+- `og:description`
+- `og:image`
+- `twitter:card`
+- `twitter:title`
+- `twitter:description`
+- `twitter:image`
+
+Use stable, publicly reachable image paths for social cards so crawlers can fetch them reliably.
+
+## Layout Props vs Metadata
+
+Keep visual layout data and SEO metadata separate.
+
+- Values returned from `layout()` are exposed as `[[ layout.* ]]`.
+- SEO values are exposed as `[[ metadata.* ]]`.
+- Do not return `title` or `description` from `layout()` expecting SEO changes.
+- The layout engine explicitly strips `title` and `description` from layout props to avoid mixing visual props with metadata.
+
+## Where To Put Defaults
+
+- Put site-wide defaults in `src/app/layout.py`.
+- Put section defaults in nested `layout.py` files such as `src/app/blog/layout.py`.
+- Put page-specific static metadata in `index.py`.
+- Put dynamic metadata inside `page()` after you have route params or fetched data.
+
+## AI Routing Notes
+
+If an AI agent is deciding where to put SEO fields, apply these rules first.
+
+- Use `Metadata` from `casp.layout` for Caspian metadata.
+- Prefer module-level `metadata = Metadata(...)` for static routes.
+- Instantiate `Metadata(...)` inside `page()` when metadata depends on params, fetched records, or generated content.
+- Put shared defaults in `layout.py` and let leaf pages override only what they need.
+- Use `extra` for Open Graph and Twitter card tags.
+- Access `extra` values in templates with bracket syntax such as `metadata['og:image']`.
+- Keep `layout()` return data in `[[ layout.* ]]` and keep SEO fields in `Metadata(...)`.
+- Check [routing.md](./routing.md) when deciding whether metadata belongs in a layout or a specific route folder.

package/dist/docs/project-structure.md

@@ -0,0 +1,193 @@
+---
+title: Project Structure
+description: Understand the default Caspian project layout so AI agents place files in the correct directories before generating PulsePoint templates, RPC actions, validation helpers, auth code, configuration, or database changes.
+related:
+  title: Related docs
+  description: Start with installation for new apps, then use the auth guide for bootstrap and session wiring, the routing guide to map URLs correctly, and the cache guide when route HTML should be reused safely.
+  links:
+    - /docs/installation
+    - /docs/auth
+    - /docs/routing
+    - /docs/cache
+    - /docs/database
+    - /docs/index
+---
+
+This page explains the default layout of a Caspian application, where Caspian core files live, and which paths AI agents should treat as project code versus framework internals.
+
+## Overview
+
+Caspian uses a lean project layout that keeps application code in `src`, database files in `prisma`, static assets in `public`, configuration in `caspian.config.json`, and framework internals in the installed package.
+
+In that layout, the default stack is PulsePoint in route templates, RPC for browser-triggered server calls, and `casp.validate` for input validation at route and action boundaries.
+
+For public pages that can safely reuse rendered HTML, Caspian also supports route-level page caching through `casp.cache_handler`.
+
+## Top-Level Areas
+
+- `src/` contains routes, page templates, styles, and shared libraries.
+- `src/lib/auth/auth_config.py` contains auth-specific configuration for the app.
+- `prisma/` contains the Prisma schema and seed scripts.
+- `public/` contains static assets served directly.
+- `main.py` is the application entry point.
+- `caspian.config.json` is the core feature configuration file.
+- `.venv/Lib/site-packages/casp/` contains the installed Caspian framework core.
+- `node_modules/caspian/dist/docs/` contains the packaged Caspian docs.
+
+## Example Layout
+
+```text
+my-app/
+  main.py
+  caspian.config.json
+  prisma/
+    schema.prisma
+    seed.ts
+  public/
+  src/
+    app/
+      layout.html
+      index.py
+      index.html
+      globals.css
+    lib/
+      auth/
+        auth_config.py
+      prisma/
+        __init__.py
+        db.py
+        models.py
+  .venv/
+    Lib/
+      site-packages/
+        casp/
+  node_modules/
+    caspian/
+      dist/
+        docs/
+```
+
+## Directory Breakdown
+
+### `src/`
+
+This is the main application area. It contains route files, templates, styles, and shared code used across the app.
+
+### `src/app/`
+
+This directory handles file-based routing. Route templates and route-specific backend logic live here.
+
+See `routing.md` for the full App Router-style rules for dynamic segments, route groups, and nested layouts.
+
+### `src/lib/`
+
+Use this folder for shared helpers, reusable validators, RPC-facing service wrappers, reusable UI utilities, and app-level support code.
+
+When Prisma ORM is enabled, this folder also contains the shared database client imports under `src/lib/prisma/`.
+
+### `src/lib/prisma/`
+
+When a Caspian app includes Prisma support, this folder contains the shared ORM imports used by route code and RPC actions.
+
+Typical files include:
+
+- `src/lib/prisma/db.py` for the shared Prisma client instance
+- `src/lib/prisma/models.py` for generated Python model types
+- `src/lib/prisma/__init__.py` for package-level re-exports such as `prisma` and `models`
+
+See `database.md` for the Prisma-specific workflow, generation step, and usage patterns.
+
+### `src/lib/auth/`
+
+Use this folder for authentication-specific project code. The main auth configuration file lives at `src/lib/auth/auth_config.py`.
+
+### `prisma/`
+
+This folder contains your database model definitions in `schema.prisma` and any seed logic such as `seed.ts`.
+
+### `public/`
+
+Store static assets here, including images, fonts, and generated frontend assets that should be served directly.
+
+## Key Files
+
+### `main.py`
+
+The application entry point for the project.
+
+In the current Caspian app shape, this file is where startup wiring happens:
+
+- load environment variables
+- call `configure_auth(build_auth_settings())`
+- register OAuth providers with `Auth.set_providers(...)`
+- create the FastAPI app
+- register routes and RPC handlers
+- add `SessionMiddleware`, CSRF middleware, auth middleware, and RPC middleware
+
+Use `main.py` for auth bootstrap and middleware-order changes. Use `src/lib/auth/auth_config.py` for auth policy values such as public routes, redirects, and RBAC maps.
+
+### `caspian.config.json`
+
+The core feature configuration file for the application.
+
+### `src/lib/auth/auth_config.py`
+
+The project auth configuration file. Use this path when changing authentication behavior.
+
+### `src/app/layout.html`
+
+The root layout shared across pages.
+
+### `src/app/index.py`
+
+The backend logic for the route. This is where route behavior can load first-render data, expose `@rpc()` actions, and import framework features such as auth helpers, `casp.validate`, and route-level `Cache(...)` declarations.
+
+### `src/app/index.html`
+
+The route template. It supports standard HTML, PulsePoint directives, and component imports, and it should be the default place for reactive frontend behavior in Caspian.
+
+### `src/app/globals.css`
+
+Global application styles.
+
+### `.venv/Lib/site-packages/casp/`
+
+The installed Caspian framework package. This is framework internals, not normal application code.
+
+Notable internal files include:
+
+- `.venv/Lib/site-packages/casp/rpc.py` for the RPC decorator and related server-action internals
+- `.venv/Lib/site-packages/casp/layout.py` for layout rendering, metadata handling, and routing-related internals
+- `.venv/Lib/site-packages/casp/cache_handler.py` for route-level cache declarations, cache manifest handling, disk-backed HTML writes, and invalidation internals
+- `.venv/Lib/site-packages/casp/validate.py` for direct validators, rule-based validation, sanitization, and file-validation internals
+
+### `node_modules/caspian/dist/docs/`
+
+The packaged Caspian documentation location distributed with the framework.
+
+## AI Routing Notes
+
+If an AI agent is deciding where to make changes, use these rules first.
+
+- Put route templates and route-specific backend logic in `src/app/`.
+- Check [routing.md](./routing.md) when you need URL segment rules, layout nesting behavior, or dynamic route conventions.
+- Put shared helpers and reusable libraries in `src/lib/`.
+- Use PulsePoint conventions in route templates for reactive frontend behavior.
+- Use `@rpc()` in route/backend code and `pp.rpc()` in client code for browser-triggered data flows.
+- Use `casp.cache_handler` when a route's first-render HTML should be reused safely across requests.
+- Use `casp.validate` at route and RPC boundaries, and move reusable validators into `src/lib/` when multiple routes share them.
+- Use `database.md` when the task involves Prisma schema changes, generated client usage, or the shared files under `src/lib/prisma/`.
+- Put authentication configuration in `src/lib/auth/auth_config.py`.
+- Put auth bootstrap, session middleware, and provider registration changes in `main.py`.
+- Put database models and seed logic in `prisma/`.
+- Put static files in `public/`.
+- Put entry-point changes in `main.py`.
+- Put feature and framework-level project configuration in `caspian.config.json`.
+- Treat `.venv/Lib/site-packages/casp/` as framework internals unless the task is specifically about Caspian core behavior.
+- Use `.venv/Lib/site-packages/casp/rpc.py` when investigating or documenting Caspian RPC internals.
+- Use `.venv/Lib/site-packages/casp/layout.py` when investigating or documenting Caspian routing, layout, or metadata internals.
+- Use `.venv/Lib/site-packages/casp/cache_handler.py` when investigating or documenting Caspian page-caching internals.
+- Use `.venv/Lib/site-packages/casp/validate.py` when investigating or documenting Caspian validation internals.
+- Look in `node_modules/caspian/dist/docs/` when you need the packaged framework docs.
+
+Check [index.md](./index.md) first if you need to choose between local Caspian docs.