create-caspian-app 0.2.0-beta.19 → 0.2.0-beta.20

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

@@ -6,17 +6,18 @@
 ## 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 as compiler-injected by the Python side; do not add it manually in authored templates unless the task is explicitly about runtime internals.
+- 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`.
+- 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
 
@@ -25,6 +26,7 @@
 - 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`
 
@@ -42,14 +44,15 @@
 
 - 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.
-- In `pp-component` roots, component logic must live in `script[type="text/pp"]`.
+- 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.
-- Keep authored route and layout templates to one top-level lowercase HTML root element, the same constraint used for component templates.
+- 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/**`
@@ -69,15 +72,16 @@
 
 - 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. `main.py`, `src/lib/**`, `public/js/**`, `prisma/**`, `src/app/**`
+	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; authored route and component templates should not add it manually
-	- route, layout, and component templates must keep a single top-level lowercase HTML root for `pp-component` injection
+	- `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`

package/dist/AGENTS.md

@@ -28,6 +28,8 @@ 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/`.
@@ -39,9 +41,11 @@ If docs differ from either of those, update the docs to match the code that actu
 - 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.
-- Route and component HTML templates must keep exactly one top-level lowercase HTML element so Caspian can inject `pp-component`.
+- `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()`.
@@ -57,6 +61,7 @@ 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` |
@@ -69,13 +74,15 @@ Use this map before making changes.
 
 - 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.
-- Keep route and component HTML templates to a single top-level lowercase HTML element so the Python side can inject `pp-component` safely.
+- 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/`.

package/package.json

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