create-caspian-app 0.2.0-beta.67 → 0.2.0-beta.68
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -35,8 +35,9 @@
|
|
|
35
35
|
- For CRUD operations and any browser-initiated reads from the backend, use route or backend `@rpc()` actions on the server and `pp.rpc(...)` from PulsePoint code on the client unless the user explicitly asks for another integration pattern.
|
|
36
36
|
- For route creation, keep page markup in `src/app/**/index.html`. If a route is UI-only, `index.html` alone is sufficient. Add `src/app/**/index.py` only as a companion when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side behavior. Do not place route HTML in `index.py`; use a lone `index.py` only for non-visual routes such as redirect-only or action-only handlers.
|
|
37
37
|
- When a single route needs to affect a wrapping layout, have `page()` return `(render_page(__file__, page_context), {"dashboard_body_class": ...})` and consume that value as `[[ layout.dashboard_body_class ]]` in `layout.html`. Use `layout.py` when the same prop should apply across a whole subtree.
|
|
38
|
-
- For file uploads and file-manager flows, keep browser interaction in route templates, keep upload and delete `@rpc()` actions in the owning `src/app/**/index.py`, keep shared storage and persistence helpers in `src/lib/**`, store metadata in Prisma, and store browser-accessible blobs under `public/
|
|
39
|
-
-
|
|
38
|
+
- For file uploads and file-manager flows, keep browser interaction in route templates, keep upload and delete `@rpc()` actions in the owning `src/app/**/index.py`, keep shared storage and persistence helpers in `src/lib/**`, store metadata in Prisma, and store browser-accessible blobs under `public/uploads/**` when the files should be served directly.
|
|
39
|
+
- Local upload helpers should create `public/uploads` on demand when it does not exist yet; do not assume the folder is committed ahead of time.
|
|
40
|
+
- When runtime uploads write into `public/uploads/**`, keep the public-root-relative entry `uploads` in `settings/bs-config.ts` `PUBLIC_IGNORE_DIRS` so `npm run dev` does not reload on each upload.
|
|
40
41
|
- For logout flows, prefer `pp.rpc("signout")` backed by `@rpc(require_auth=True)` from page-level or component-level UI. Use a dedicated signout route only for plain form POST, no-JavaScript fallback, or other full-navigation edge cases.
|
|
41
42
|
- Protect customized `src/lib/auth/auth_config.py` from updater overwrite by adding `./src/lib/auth/auth_config.py` to `excludeFiles` in `caspian.config.json`.
|
|
42
43
|
- 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.
|
package/dist/AGENTS.md
CHANGED
|
@@ -83,10 +83,11 @@ Important rules:
|
|
|
83
83
|
- `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.
|
|
84
84
|
- `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.
|
|
85
85
|
- 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>`.
|
|
86
|
-
- File-manager flows in this repo should keep upload and delete `@rpc()` actions in the owning `src/app/**/index.py`, keep shared filesystem and Prisma helpers in `src/lib/**`, persist metadata in Prisma, and store browser-accessible blobs under `public/
|
|
86
|
+
- File-manager flows in this repo should keep upload and delete `@rpc()` actions in the owning `src/app/**/index.py`, keep shared filesystem and Prisma helpers in `src/lib/**`, persist metadata in Prisma, and store browser-accessible blobs under `public/uploads/**` when they should be served directly.
|
|
87
|
+
- Local upload helpers should create `public/uploads` on demand if the directory does not exist yet.
|
|
87
88
|
- When `npm run dev` is intentionally running, let that long-running stack own generated outputs such as `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files. Treat those as generated artifacts, not authored source.
|
|
88
89
|
- `settings/component-map.json` and `settings/files-list.json` are generated by `settings/component-map.ts` and `settings/files-list.ts` through the dev and build pipelines. Analyze them when needed, but do not hand-edit them.
|
|
89
|
-
- `settings/bs-config.ts` should keep
|
|
90
|
+
- `settings/bs-config.ts` should keep the public-root-relative upload directory name `uploads` in `PUBLIC_IGNORE_DIRS` so runtime uploads under `public/uploads/**` do not trigger BrowserSync reloads during the local stack.
|
|
90
91
|
- In the current router inside `main.py`, path params are passed to `page()` as the first positional `dict` argument.
|
|
91
92
|
- Matching query params can still be injected by name, and `request` is injected by keyword when declared.
|
|
92
93
|
- The installed `casp.layout` runtime calls `layout()` synchronously. Keep async I/O in `page()` or `@rpc()`.
|
|
@@ -123,7 +124,7 @@ Use this map before making changes.
|
|
|
123
124
|
- Keep route-specific logic in `src/app/**`.
|
|
124
125
|
- For route creation, keep page markup in `src/app/**/index.html`. If a route is UI-only, `index.html` alone is sufficient. Add `src/app/**/index.py` only as a companion when the same route needs metadata, `page()`, `@rpc()` actions, auth checks, caching, redirects, or other server-side behavior. Do not place route HTML in `index.py`; use a lone `index.py` only for non-visual routes such as redirect-only or action-only handlers.
|
|
125
126
|
- If a single route only needs to tweak a parent layout, return `(render_page(__file__, ...), {"dashboard_body_class": ...})` from `page()` instead of introducing one-off global state or moving route HTML into `index.py`.
|
|
126
|
-
- For file-manager work, keep route-owned upload and delete `@rpc()` actions in `src/app/**/index.py`, keep shared storage and Prisma helper logic in `src/lib/**`,
|
|
127
|
+
- For file-manager work, keep route-owned upload and delete `@rpc()` actions in `src/app/**/index.py`, keep shared storage and Prisma helper logic in `src/lib/**`, keep uploaded public blobs under `public/uploads/**`, and create that directory on demand in the helper when it is missing.
|
|
127
128
|
- When deciding between `src/components/**` and `src/lib/**`, put reusable rendered UI in `src/components/**` and put services, validators, adapters, database helpers, and other non-UI support code in `src/lib/**`.
|
|
128
129
|
- Read `caspian.config.json` before deciding whether a Caspian feature should be used, documented, scaffolded, or avoided in the current workspace.
|
|
129
130
|
- Treat `caspian.config.json` as the single source of truth for optional features. Do not use feature-specific files, commands, or docs until the corresponding flag is enabled.
|