create-caspian-app 0.2.0-beta.2 → 0.2.0-beta.21

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

@@ -0,0 +1,88 @@
+# Copilot Instructions
+
+- Read `AGENTS.md` before working in `main.py`, `src/lib/**`, `.venv/Lib/site-packages/casp/**`, `public/js/**`, `prisma/**`, or `node_modules/caspian-utils/dist/docs/**`.
+- Keep all repo-level Copilot guidance in this file. Do not add `.github/instructions/` for this workspace.
+
+## Global Rules
+
+- Use this source-of-truth order: app runtime and app-owned code first, installed `casp` runtime second, packaged markdown docs third.
+- Read `./caspian.config.json` almost immediately before making feature, tooling, scaffolding, or file-placement decisions. Treat it as the workspace feature gate for flags such as `backendOnly`, `tailwindcss`, `mcp`, `prisma`, `typescript`, and `componentScanDirs`.
+- For current repo behavior, trust `main.py`, `src/lib/**`, `public/js/**`, `prisma/**`, and `src/app/**` over generic Caspian docs.
+- For framework internals, trust `.venv/Lib/site-packages/casp/**` over generic or older upstream guidance.
+- When docs and runtime disagree, align the docs to the code that actually runs in this workspace.
+- Reuse the existing Python database layer in `src/lib/prisma/**`; do not create a second app-owned database abstraction unless the user explicitly asks for one.
+- Keep auth policy in `src/lib/auth/auth_config.py` and keep auth bootstrap, middleware wiring, and provider registration in `main.py`.
+- Use PulsePoint and `pp.rpc(...)` as the default frontend and client-to-server contract unless the user requests another stack.
+- Treat `pp-component` on routes, layouts, and components, and `type="text/pp"` on owned PulsePoint scripts, as compiler-injected by the Python side; do not add them manually in authored templates unless the task is explicitly about runtime internals.
+- `layout()` is synchronous in the installed runtime. Put async I/O in `page()` or `@rpc()`.
+- Dynamic route params currently reach `page()` as a single positional `dict`, with query params injected by name and `request` injected by keyword when declared.
+- Do not assume `StateManager` survives across requests unless `request.state.session` is explicitly bridged from `request.session`.
+- Route, layout, and component HTML templates must keep a single top-level lowercase HTML element so Caspian can inject `pp-component`. Think React-style single parent wrapper: good one root containing the markup and any owned PulsePoint script, bad sibling top-level tags.
+
+## Path-Specific Rules
+
+### `main.py`
+
+- Treat `main.py` as the repo source of truth for FastAPI setup, static asset routes, auth bootstrap, middleware order, route registration, cache defaults, and error handlers.
+- Preserve the effective middleware execution order unless the task explicitly changes request semantics: `SessionMiddleware -> CSRFMiddleware -> AuthMiddleware -> RPCMiddleware`.
+- Document route param behavior exactly as implemented here.
+- Do not use `main.py` alone to infer whether optional features are enabled; confirm that in `caspian.config.json` first.
+
+### `src/lib/**/*.py`
+
+- Keep `src/lib/` for app-owned shared code, service wrappers, and reusable helpers.
+- Reuse and extend the existing `src/lib/prisma/` package for Python database access.
+- Keep auth policy in `src/lib/auth/auth_config.py`. Keep auth bootstrap and middleware order changes in `main.py`.
+
+### `public/js/main.js`
+
+- Treat `public/js/main.js` as the thin browser bootstrap entry point.
+- Keep it minimal and point it at the runtime shipped in `public/js/pp-reactive-v2.js`.
+- Do not duplicate PulsePoint runtime logic here.
+
+### `public/js/pp-reactive-v2.js`
+
+- Treat `public/js/pp-reactive-v2.js` as the browser-side PulsePoint runtime source of truth for component execution, refs, directives, SPA navigation, and `pp.rpc(...)` behavior.
+- Preserve the current public runtime contract unless the task explicitly changes Caspian frontend behavior.
+- At runtime, component logic is discovered from `script[type="text/pp"]` inside `pp-component` roots. In authored route, layout, and component templates, write plain `<script>` and let `main.py` plus `casp.scripts_type.transform_scripts(...)` add the type.
+
+### `src/app/**/*.html`
+
+- Keep route templates and layouts server-rendered first, with PulsePoint enhancement as the default interactive layer.
+- Preserve Caspian template syntax such as `[[...]]` in layouts and `pp-*` runtime attributes in rendered HTML.
+- Do not author `pp-component="..."` manually in route or layout templates; the Python render pipeline injects it onto the single root element.
+- Do not author `type="text/pp"` manually in route or layout templates either. Use plain `<script>` in source and let the render path rewrite it.
+- Keep authored route and layout templates to one top-level lowercase HTML root element, the same constraint used for component templates. If a script is needed, keep it inside that root instead of as a sibling top-level node.
+- Do not assume React, Vue, JSX, HTMX, or another frontend runtime unless the user explicitly requests one.
+
+### `prisma/**`
+
+- Treat `prisma/schema.prisma` as the data-model source of truth.
+- Treat `prisma.config.ts` as the datasource and migration or seed configuration source of truth.
+- Keep Node-side generation and seeding aligned with `npx prisma generate` and `prisma/seed.ts`.
+- Keep Python-side database access aligned with `src/lib/prisma/**`.
+
+### `.venv/Lib/site-packages/casp/**/*.py`
+
+- Treat these files as framework internals.
+- Only change them when the task is explicitly about Caspian core behavior, installed-runtime debugging, or documentation that must match the installed implementation.
+- If behavior changes here, update the matching docs under `node_modules/caspian-utils/dist/docs/`.
+
+### `node_modules/caspian-utils/dist/docs/**/*.md`
+
+- These files are the local documentation layer, not the runtime. Verify every behavior claim against the actual code that runs.
+- Use this verification order:
+	1. `caspian.config.json`, then `main.py`, `src/lib/**`, `public/js/**`, `prisma/**`, `src/app/**`
+	2. `.venv/Lib/site-packages/casp/**`
+	3. the markdown file being edited
+- Keep repo-specific facts accurate when they matter:
+	- `caspian.config.json` is the first config file to read for enabled workspace features and scan directories
+	- this workspace already has `src/lib/prisma/**`
+	- auth policy lives in `src/lib/auth/auth_config.py`
+	- PulsePoint runtime lives in `public/js/pp-reactive-v2.js`
+	- `pp-component` is injected by the Python render pipeline, and `main.py` rewrites authored body scripts to `type="text/pp"`; authored route, layout, and component templates should not add those attributes manually
+	- route, layout, and component templates must keep a single top-level lowercase HTML root for `pp-component` injection, with any owned plain `<script>` kept inside that same root
+	- dynamic route params are passed to `page()` as a single positional `dict`
+	- `layout()` is sync-only in the installed runtime
+	- `StateManager` persistence depends on `request.state.session`, which is not bridged from `request.session` in the current `main.py`
+- Keep `index.md` and cross-links aligned when adding or changing pages.

package/dist/AGENTS.md

@@ -0,0 +1,105 @@
+# Caspian Agent Guide
+
+## Purpose
+
+This workspace is a Caspian application plus a local copy of the packaged Caspian docs.
+
+When you work here, use the code that actually runs as the source of truth and use the markdown docs as the routing and explanation layer.
+
+## Source Of Truth Order
+
+Use this precedence whenever behavior, docs, and generated code disagree:
+
+1. App runtime and app-owned code
+   - `main.py`
+   - `src/app/**`
+   - `src/lib/**`
+   - `public/js/**`
+   - `prisma/**`
+   - `caspian.config.json`
+2. Installed Caspian framework runtime
+   - `.venv/Lib/site-packages/casp/**`
+3. Packaged Caspian docs in this workspace
+   - `node_modules/caspian-utils/dist/docs/**`
+
+If the task is about current repo behavior, prefer the app runtime.
+
+If the task is about framework internals, prefer the installed `casp` package.
+
+If docs differ from either of those, update the docs to match the code that actually runs.
+
+Before making feature, tooling, or scaffolding decisions, read `caspian.config.json` almost immediately. Treat it as the workspace feature gate for flags such as `backendOnly`, `tailwindcss`, `mcp`, `prisma`, `typescript`, and `componentScanDirs`.
+
+## Verified Workspace Facts
+
+- Local Caspian docs live under `node_modules/caspian-utils/dist/docs/`.
+- `main.py` is the application entry point and owns auth bootstrap, FastAPI setup, static asset routes, route registration, error handlers, cache defaults, and middleware wiring.
+- Middleware is added in this source order: `RPCMiddleware`, `AuthMiddleware`, `CSRFMiddleware`, `SessionMiddleware`.
+- Effective request order is therefore: `SessionMiddleware -> CSRFMiddleware -> AuthMiddleware -> RPCMiddleware`.
+- App-level auth policy lives in `src/lib/auth/auth_config.py`.
+- `main.py` applies auth settings with `configure_auth(build_auth_settings())` and registers `GithubProvider()` plus `GoogleProvider()`.
+- This workspace already has an app-owned Python database layer in `src/lib/prisma/`.
+- Reuse `src/lib/prisma/prisma`, `PrismaClient`, generated models, and helper types instead of creating a second Python database abstraction.
+- Prisma schema source of truth is `prisma/schema.prisma`, and the local Node workflow still uses `npx prisma generate` plus `prisma/seed.ts`.
+- `caspian.config.json` is the first config file to check for enabled workspace features. In the current workspace it sets `backendOnly: false`, `tailwindcss: true`, `mcp: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+- PulsePoint runtime code is shipped in `public/js/pp-reactive-v2.js` and loaded from `public/js/main.js`.
+- `pp-component` is injected by the Python render pipeline onto page, layout, and component roots; authored route and component templates should not add it manually.
+- `main.py` runs `transform_scripts(...)`, so authored body `<script>` tags are rewritten to `<script type="text/pp">` in rendered HTML; route, layout, and component templates should write plain `<script>` in source.
+- Route and component HTML templates must keep exactly one top-level lowercase HTML element so Caspian can inject `pp-component`. Think React-style single parent wrapper: good `<div>...</div>` with any owned script inside that same root, bad sibling top-level tags such as `<div>...</div><script ...></script>`.
+- In the current router inside `main.py`, path params are passed to `page()` as the first positional `dict` argument.
+- Matching query params can still be injected by name, and `request` is injected by keyword when declared.
+- The installed `casp.layout` runtime calls `layout()` synchronously. Keep async I/O in `page()` or `@rpc()`.
+- `StateManager` reads and writes `request.state.session`, but the current middleware stack in `main.py` does not mirror `request.session` into `request.state.session`.
+- Do not assume `StateManager` persistence survives across requests until that bridge exists.
+- Route HTML caching uses `caches/` and `caches/cache_manifest.json` through `casp.cache_handler`.
+- The current app tree has root templates in `src/app/` and does not currently include route-specific `index.py` files.
+
+## Task Routing
+
+Use this map before making changes.
+
+| Task area | Read first | Verify against |
+| --- | --- | --- |
+| Project layout and file placement | `node_modules/caspian-utils/dist/docs/index.md`, `node_modules/caspian-utils/dist/docs/project-structure.md` | current workspace tree |
+| Feature availability and tooling switches | `caspian.config.json` | current workspace tree, `main.py`, `prisma/**`, `public/js/**` |
+| Routing, layouts, metadata | `node_modules/caspian-utils/dist/docs/routing.md` | `main.py`, `.venv/Lib/site-packages/casp/layout.py` |
+| Auth, sessions, RBAC, providers | `node_modules/caspian-utils/dist/docs/auth.md` | `src/lib/auth/auth_config.py`, `main.py`, `.venv/Lib/site-packages/casp/auth.py` |
+| RPC, data loading, streaming, uploads | `node_modules/caspian-utils/dist/docs/fetch-data.md`, `node_modules/caspian-utils/dist/docs/pulsepoint.md` | `.venv/Lib/site-packages/casp/rpc.py`, `public/js/pp-reactive-v2.js`, `main.py` |
+| Server state | `node_modules/caspian-utils/dist/docs/state.md` | `.venv/Lib/site-packages/casp/state_manager.py`, `main.py` |
+| Page caching | `node_modules/caspian-utils/dist/docs/cache.md` | `.venv/Lib/site-packages/casp/cache_handler.py`, `main.py` |
+| Validation | `node_modules/caspian-utils/dist/docs/validation.md` | `.venv/Lib/site-packages/casp/validate.py` |
+| Database and seed flow | `node_modules/caspian-utils/dist/docs/database.md` | `prisma/schema.prisma`, `prisma/seed.ts`, `src/lib/prisma/**` |
+
+## Editing Rules
+
+- Keep app-owned shared code in `src/lib/**`.
+- Keep route-specific logic in `src/app/**`.
+- Read `caspian.config.json` before deciding whether a Caspian feature should be used, documented, scaffolded, or avoided in the current workspace.
+- Treat `.venv/Lib/site-packages/casp/**` as framework internals unless the task is explicitly about Caspian core behavior or installed-runtime documentation.
+- When a task involves Python-side database access, extend or reuse `src/lib/prisma/**` instead of introducing a parallel helper.
+- Keep auth policy in `src/lib/auth/auth_config.py`.
+- Keep auth bootstrap, middleware ordering, provider wiring, and router behavior in `main.py`.
+- Use PulsePoint and `pp.rpc(...)` as the default frontend and browser-to-server contract unless the user explicitly wants another stack.
+- Treat `pp-component` as a framework-owned attribute on authored templates. Document it, but do not manually add it in normal route or component HTML.
+- Treat `type="text/pp"` on PulsePoint scripts as a render-time attribute too. In authored route, layout, and component HTML, write plain `<script>` and let Caspian rewrite it.
+- Keep route and component HTML templates to a single top-level lowercase HTML element so the Python side can inject `pp-component` safely. Keep any owned PulsePoint script inside that same root instead of as a sibling top-level node.
+- Keep Copilot guidance consolidated in `.github/copilot-instructions.md`; do not add `.github/instructions/` in this workspace.
+- When writing docs about route behavior, describe the param passing and layout behavior implemented in the current runtime, not generic upstream assumptions.
+- When a runtime change affects documentation, update the matching page in `node_modules/caspian-utils/dist/docs/`.
+- When a repo-level rule changes, update this file too.
+
+## Docs Alignment Notes
+
+The packaged docs in this workspace are already mostly aligned with the installed runtime, but keep these repo-specific clarifications in mind:
+
+- `database.md` describes the scaffold generically, but this workspace now includes a real app-owned Python Prisma-style layer under `src/lib/prisma/`.
+- `state.md` is correct to warn that cross-request persistence depends on `request.state.session`, which is not bridged in the current `main.py`.
+- `routing.md`, `components.md`, `auth.md`, `fetch-data.md`, `cache.md`, `pulsepoint.md`, and `validation.md` should continue to be validated against the installed `casp` package before any behavior claims are changed.
+
+## Maintenance Checklist
+
+Before merging doc or runtime changes:
+
+1. Compare the claim or behavior against `main.py`, `src/lib/**`, and `.venv/Lib/site-packages/casp/**`.
+2. Update the matching packaged doc in `node_modules/caspian-utils/dist/docs/` if the running behavior changed.
+3. Update this file if the repo-level source-of-truth rules or workspace facts changed.

package/dist/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md