create-caspian-app 0.2.0-beta.33 → 0.2.0-beta.35
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.
|
@@ -7,15 +7,28 @@
|
|
|
7
7
|
|
|
8
8
|
- Use this source-of-truth order: app runtime and app-owned code first, installed `casp` runtime second, packaged markdown docs third.
|
|
9
9
|
- 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`.
|
|
10
|
+
- Treat `caspian.config.json` as the single source of truth for whether optional Caspian features are enabled in the current workspace. Use feature-specific docs, files, and commands only after the matching flag is confirmed as enabled.
|
|
11
|
+
- If a feature is disabled and the user wants it, ask whether they want to enable it first, then update `caspian.config.json` and follow `npx casp update project` so framework-managed files align with the new feature set.
|
|
10
12
|
- For current repo behavior, trust `main.py`, `src/lib/**`, `public/js/**`, `prisma/**`, and `src/app/**` over generic Caspian docs.
|
|
11
13
|
- For framework internals, trust `.venv/Lib/site-packages/casp/**` over generic or older upstream guidance.
|
|
12
14
|
- When docs and runtime disagree, align the docs to the code that actually runs in this workspace.
|
|
13
15
|
- When `prisma/schema.prisma` changes, follow this order: run `npx prisma migrate dev`; if the change affects seed flow or `prisma/seed.ts`, run `npx prisma generate` and then `npx prisma db seed`; then run `npx ppy generate` so the Python ORM stays aligned with the schema.
|
|
14
16
|
- 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.
|
|
15
17
|
- Treat `src/lib/prisma/__init__.py`, `src/lib/prisma/db.py`, `src/lib/prisma/models.py`, and `settings/prisma-schema.json` as generated outputs owned by `npx ppy generate`; do not create or hand-edit them manually.
|
|
18
|
+
- Treat `package.json` scripts as opt-in operations. Do not run `npm run dev`, `npm run build`, or other npm scripts unless the user explicitly asks, the task genuinely requires that exact script, or deployment preparation needs `npm run build`.
|
|
19
|
+
- Use `npm run build` for deployment prep or an explicit build request, not as the default validation step for routine route, feature, or documentation edits.
|
|
20
|
+
- Let the running dev 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 rather than authored source.
|
|
21
|
+
- Never treat `__pycache__/` directories or `.pyc` files as files to edit, regenerate on purpose, or keep in the final diff.
|
|
22
|
+
- Treat `settings/component-map.json` and `settings/files-list.json` as generated outputs owned by `settings/component-map.ts` and `settings/files-list.ts`; inspect them when needed, but do not hand-edit them.
|
|
16
23
|
- When `caspian.config.json` has `mcp: true`, treat `src/lib/mcp/mcp_server.py` as the app-owned FastMCP server and `src/lib/mcp/fastmcp.json` as the default MCP config. Use `npm run mcp` or `fastmcp run src/lib/mcp/fastmcp.json`; do not assume root `fastmcp.json` auto-discovery.
|
|
17
24
|
- Keep auth policy in `src/lib/auth/auth_config.py` and keep auth bootstrap, middleware wiring, and provider registration in `main.py`.
|
|
25
|
+
- In app-owned starter config like this workspace, routes start public because `src/lib/auth/auth_config.py` sets `is_all_routes_private=False` by default.
|
|
26
|
+
- Decide route privacy in `src/lib/auth/auth_config.py` at app setup time: use `is_all_routes_private=True` when only a few routes should stay public, otherwise keep `is_all_routes_private=False` and list the protected routes in `private_routes`.
|
|
27
|
+
- In all-private mode, keep public exceptions in `public_routes`; the runtime defaults keep `/` public and keep `auth_routes=["/signin", "/signup"]` public.
|
|
28
|
+
- Do not treat `token_auto_refresh` as the switch that makes routes private. In the current app it only affects sliding-session refresh if `auth.refresh_session()` is called.
|
|
18
29
|
- Use PulsePoint and `pp.rpc(...)` as the default frontend and client-to-server contract unless the user requests another stack.
|
|
30
|
+
- 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.
|
|
31
|
+
- 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`.
|
|
19
32
|
- 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.
|
|
20
33
|
- `layout()` is synchronous in the installed runtime. Put async I/O in `page()` or `@rpc()`.
|
|
21
34
|
- Dynamic route params currently reach `page()` as a single positional `dict`, with query params injected by name and `request` injected by keyword when declared.
|
|
@@ -35,7 +48,7 @@
|
|
|
35
48
|
|
|
36
49
|
- Keep `src/lib/` for app-owned shared code, service wrappers, and reusable helpers.
|
|
37
50
|
- Reuse the generated `src/lib/prisma/` package for Python database access, but do not hand-edit files under `src/lib/prisma/`; regenerate them with `npx ppy generate` after schema changes.
|
|
38
|
-
-
|
|
51
|
+
- When `caspian.config.json` has `mcp: true`, keep app-owned MCP tools in `src/lib/mcp/mcp_server.py` and keep the default FastMCP config in `src/lib/mcp/fastmcp.json`. If those locations change, update `settings/restart-mcp.ts` and the MCP docs together.
|
|
39
52
|
- Keep auth policy in `src/lib/auth/auth_config.py`. Keep auth bootstrap and middleware order changes in `main.py`.
|
|
40
53
|
|
|
41
54
|
### `public/js/main.js`
|
|
@@ -84,11 +97,21 @@
|
|
|
84
97
|
3. the markdown file being edited
|
|
85
98
|
- Keep repo-specific facts accurate when they matter:
|
|
86
99
|
- `caspian.config.json` is the first config file to read for enabled workspace features and scan directories
|
|
100
|
+
- `caspian.config.json` is the single source of truth for whether an optional feature is enabled in the current workspace
|
|
87
101
|
- this workspace already has `src/lib/prisma/**`
|
|
88
|
-
- this workspace
|
|
89
|
-
-
|
|
90
|
-
-
|
|
102
|
+
- this workspace currently has `mcp: false` in `caspian.config.json`, so do not assume `src/lib/mcp/**`, `settings/restart-mcp.ts`, or `npm run mcp` exist until MCP is explicitly enabled
|
|
103
|
+
- `package.json` currently defines `projectName`, `tailwind`, `tailwind:build`, `browserSync`, `browserSync:build`, `dev`, and `build`
|
|
104
|
+
- if a feature flag is false and the user wants that feature, ask before enabling it, then update `caspian.config.json` and use `npx casp update project` to refresh framework-managed files
|
|
105
|
+
- do not run `package.json` scripts by default for ordinary source edits; only use them when the user explicitly asks, the task requires them, or deployment prep needs `npm run build`
|
|
106
|
+
- `npm run dev` is a long-running local stack command that can regenerate `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` artifacts; those are generated outputs, not authored source files
|
|
107
|
+
- `settings/component-map.ts` and `settings/files-list.ts` own `settings/component-map.json` and `settings/files-list.json`; inspect the JSON when needed, but let the framework regenerate it instead of editing it by hand
|
|
91
108
|
- auth policy lives in `src/lib/auth/auth_config.py`
|
|
109
|
+
- the app-owned starter config in this workspace begins public-first with `is_all_routes_private=False`, so treat routes as public by default unless the app explicitly switches to all-private mode
|
|
110
|
+
- choose all-private mode in `src/lib/auth/auth_config.py` only when public routes are the minority; otherwise keep mixed mode and maintain `private_routes`
|
|
111
|
+
- `public_routes` is the exception list for all-private apps, while `auth_routes=["/signin", "/signup"]` stays public by default unless the app explicitly needs different auth endpoints
|
|
112
|
+
- `token_auto_refresh` is not the route-privacy switch in the current app; it only matters when `auth.refresh_session()` is called
|
|
113
|
+
- protect customized `src/lib/auth/auth_config.py` by adding `./src/lib/auth/auth_config.py` to `excludeFiles` in `caspian.config.json`
|
|
114
|
+
- prefer logout via `pp.rpc("signout")` plus `@rpc(require_auth=True)` from page or component UI; use a dedicated signout route only for form-post or no-JavaScript fallbacks
|
|
92
115
|
- PulsePoint runtime lives in `public/js/pp-reactive-v2.js`
|
|
93
116
|
- `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
|
|
94
117
|
- 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
|
package/dist/AGENTS.md
CHANGED
|
@@ -30,6 +30,8 @@ If docs differ from either of those, update the docs to match the code that actu
|
|
|
30
30
|
|
|
31
31
|
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`.
|
|
32
32
|
|
|
33
|
+
Treat `caspian.config.json` as the single source of truth for whether an optional Caspian feature is enabled in the current workspace. Use feature-specific docs only after the matching flag is confirmed as enabled. If a feature is disabled and the user wants it, ask whether they want to enable it first, then follow the Caspian update workflow to refresh framework-managed files.
|
|
34
|
+
|
|
33
35
|
## Verified Workspace Facts
|
|
34
36
|
|
|
35
37
|
- Local Caspian docs live under `node_modules/caspian-utils/dist/docs/`.
|
|
@@ -38,18 +40,26 @@ Before making feature, tooling, or scaffolding decisions, read `caspian.config.j
|
|
|
38
40
|
- Effective request order is therefore: `SessionMiddleware -> CSRFMiddleware -> AuthMiddleware -> RPCMiddleware`.
|
|
39
41
|
- App-level auth policy lives in `src/lib/auth/auth_config.py`.
|
|
40
42
|
- `main.py` applies auth settings with `configure_auth(build_auth_settings())` and registers `GithubProvider()` plus `GoogleProvider()`.
|
|
43
|
+
- In the app-owned starter config used in this workspace, routes start public because `src/lib/auth/auth_config.py` sets `is_all_routes_private=False` by default.
|
|
44
|
+
- Choose route privacy mode in `src/lib/auth/auth_config.py` at app setup time: use `is_all_routes_private=True` when most routes should require auth, otherwise keep `is_all_routes_private=False` and list only the protected routes in `private_routes`.
|
|
45
|
+
- In all-private mode, treat `public_routes` as the exception list. The runtime defaults keep `/` public and keep `auth_routes=["/signin", "/signup"]` public.
|
|
46
|
+
- `token_auto_refresh` does not make routes private in the current app; it only affects sliding-session refresh if `auth.refresh_session()` is called.
|
|
47
|
+
- Prefer logout via auth-protected RPC from page-level or component-level UI: `pp.rpc("signout")` backed by `@rpc(require_auth=True)`. Use a dedicated signout route only for plain form POST or no-JavaScript edge cases.
|
|
48
|
+
- Protect customized `src/lib/auth/auth_config.py` from framework updates by adding `./src/lib/auth/auth_config.py` to `excludeFiles` in `caspian.config.json`.
|
|
41
49
|
- This workspace already has an app-owned Python database layer in `src/lib/prisma/`.
|
|
42
|
-
- This workspace
|
|
43
|
-
- `package.json`
|
|
50
|
+
- This workspace currently has `mcp: false` in `caspian.config.json`, so do not assume `src/lib/mcp/**`, `settings/restart-mcp.ts`, or `npm run mcp` exist unless MCP is explicitly enabled later.
|
|
51
|
+
- `package.json` currently defines `projectName`, `tailwind`, `tailwind:build`, `browserSync`, `browserSync:build`, `dev`, and `build`. Treat those scripts as opt-in operational commands, not default validation steps for ordinary source edits.
|
|
44
52
|
- Reuse `src/lib/prisma/prisma`, `PrismaClient`, generated models, and helper types instead of creating a second Python database abstraction.
|
|
45
53
|
- Prisma schema source of truth is `prisma/schema.prisma`.
|
|
46
54
|
- The schema-change workflow in this workspace is: `npx prisma migrate dev`; if seed flow or `prisma/seed.ts` is involved, run `npx prisma generate` and then `npx prisma db seed`; then run `npx ppy generate`.
|
|
47
55
|
- `npx ppy generate` owns `src/lib/prisma/__init__.py`, `src/lib/prisma/db.py`, `src/lib/prisma/models.py`, and `settings/prisma-schema.json`; do not hand-edit those generated files.
|
|
48
|
-
- `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:
|
|
56
|
+
- `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"]`.
|
|
49
57
|
- PulsePoint runtime code is shipped in `public/js/pp-reactive-v2.js` and loaded from `public/js/main.js`.
|
|
50
58
|
- `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.
|
|
51
59
|
- `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.
|
|
52
60
|
- 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>`.
|
|
61
|
+
- 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.
|
|
62
|
+
- `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.
|
|
53
63
|
- In the current router inside `main.py`, path params are passed to `page()` as the first positional `dict` argument.
|
|
54
64
|
- Matching query params can still be injected by name, and `request` is injected by keyword when declared.
|
|
55
65
|
- The installed `casp.layout` runtime calls `layout()` synchronously. Keep async I/O in `page()` or `@rpc()`.
|
|
@@ -80,11 +90,22 @@ Use this map before making changes.
|
|
|
80
90
|
- Keep app-owned shared code in `src/lib/**`.
|
|
81
91
|
- Keep route-specific logic in `src/app/**`.
|
|
82
92
|
- Read `caspian.config.json` before deciding whether a Caspian feature should be used, documented, scaffolded, or avoided in the current workspace.
|
|
93
|
+
- 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.
|
|
94
|
+
- If a feature flag is false and the user wants that feature, ask for confirmation first, then update `caspian.config.json` and run `npx casp update project` so framework-managed files align with the new feature set.
|
|
95
|
+
- Do not run `package.json` scripts unless the user explicitly asks for them, the task genuinely requires that exact script, or deployment preparation needs `npm run build`.
|
|
96
|
+
- Use `npm run build` for deployment prep or an explicit build request, not as the default validation step for routine route, feature, or documentation edits.
|
|
97
|
+
- Never treat `__pycache__/` directories or `.pyc` files as authored source. Do not edit them manually and do not leave them in the final diff if a tool run creates them.
|
|
98
|
+
- Never hand-edit `settings/component-map.json` or `settings/files-list.json`. Inspect them if needed, but let the framework regeneration flow update them.
|
|
83
99
|
- Treat `.venv/Lib/site-packages/casp/**` as framework internals unless the task is explicitly about Caspian core behavior or installed-runtime documentation.
|
|
84
100
|
- When a task involves Python-side database access, reuse `src/lib/prisma/**` instead of introducing a parallel helper, but do not hand-edit generated files in that directory.
|
|
85
101
|
- When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first. If seed flow or `prisma/seed.ts` is involved, run `npx prisma generate` and then `npx prisma db seed`. After that, run `npx ppy generate` so the Python ORM layer and `settings/prisma-schema.json` stay aligned.
|
|
86
102
|
- Keep auth policy in `src/lib/auth/auth_config.py`.
|
|
87
103
|
- Keep auth bootstrap, middleware ordering, provider wiring, and router behavior in `main.py`.
|
|
104
|
+
- Treat the app-owned `src/lib/auth/auth_config.py` as the effective default when generating routes for this repo: it starts public-first with `is_all_routes_private=False` unless the app explicitly switches to all-private mode.
|
|
105
|
+
- Decide all-private versus mixed public/private routing in `src/lib/auth/auth_config.py` before creating many routes; use all-private mode only when public routes are the minority.
|
|
106
|
+
- Keep public exceptions in `public_routes`, keep explicit protected routes in `private_routes` when not using all-private mode, and leave default `auth_routes` alone unless the app explicitly needs custom auth endpoints.
|
|
107
|
+
- Do not treat `token_auto_refresh` as the switch for private routes.
|
|
108
|
+
- For logout flows, prefer `pp.rpc("signout")` plus `@rpc(require_auth=True)` in page or component UI. Only scaffold a signout route for no-JavaScript, form-post, or full-navigation edge cases.
|
|
88
109
|
- When MCP is enabled, keep the app-owned FastMCP server in `src/lib/mcp/mcp_server.py` and the default config in `src/lib/mcp/fastmcp.json`. If those paths move, update `settings/restart-mcp.ts` and the MCP docs together.
|
|
89
110
|
- Use PulsePoint and `pp.rpc(...)` as the default frontend and browser-to-server contract unless the user explicitly wants another stack.
|
|
90
111
|
- 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.
|
|
@@ -100,8 +121,11 @@ Use this map before making changes.
|
|
|
100
121
|
The packaged docs in this workspace are already mostly aligned with the installed runtime, but keep these repo-specific clarifications in mind:
|
|
101
122
|
|
|
102
123
|
- `database.md` is the source doc for the Prisma and Python ORM workflow in this repo: schema changes go through `npx prisma migrate dev`, optional `npx prisma generate` plus `npx prisma db seed`, then `npx ppy generate`, and generated ORM files under `src/lib/prisma/` plus `settings/prisma-schema.json` are not hand-edited.
|
|
103
|
-
- `mcp.md` is the source doc for
|
|
124
|
+
- `mcp.md` is the source doc for MCP-enabled workspaces, but in this workspace `caspian.config.json` currently has `mcp: false`, so do not assume `src/lib/mcp/**` or `npm run mcp` exist until MCP is explicitly enabled.
|
|
125
|
+
- Feature-specific docs are conditional on `caspian.config.json`: use `database.md` only when `prisma: true`, use `mcp.md` only when `mcp: true`, and treat disabled-feature docs as reference material until the user chooses to enable that feature.
|
|
126
|
+
- `auth.md` is the source doc for auth routing guidance: choose all-private mode only when public routes are the minority, keep auth policy in `src/lib/auth/auth_config.py`, protect that file with `excludeFiles` if customized, prefer auth-protected RPC logout from page or component UI, and keep dedicated signout routes for form-post or no-JavaScript fallbacks.
|
|
104
127
|
- `state.md` is correct to warn that cross-request persistence depends on `request.state.session`, which is not bridged in the current `main.py`.
|
|
128
|
+
- `commands.md`, `installation.md`, and `project-structure.md` are the source docs for this repo's package-script guardrails: do not auto-run npm scripts for ordinary edits, use `npm run build` only for deployment prep or explicit build requests, and treat `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files as generated artifacts.
|
|
105
129
|
- `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.
|
|
106
130
|
|
|
107
131
|
## Maintenance Checklist
|
|
@@ -8,16 +8,25 @@ def build_auth_settings() -> AuthSettings:
|
|
|
8
8
|
|
|
9
9
|
Keep secrets (AUTH_SECRET, AUTH_COOKIE_NAME) in .env.
|
|
10
10
|
Keep app-level session settings in .env (SESSION_LIFETIME_HOURS, etc).
|
|
11
|
+
Decide route privacy here at app setup time instead of changing Caspian core files.
|
|
12
|
+
|
|
13
|
+
Rule of thumb:
|
|
14
|
+
- If most routes should require auth, set is_all_routes_private=True and list only the public exceptions.
|
|
15
|
+
- If many routes should stay public, keep is_all_routes_private=False and list only the protected routes.
|
|
11
16
|
"""
|
|
12
17
|
|
|
13
18
|
return AuthSettings(
|
|
14
19
|
# Token settings
|
|
15
20
|
default_token_validity="1h",
|
|
21
|
+
# Sliding-session refresh only matters when the request flow calls auth.refresh_session().
|
|
16
22
|
token_auto_refresh=False,
|
|
17
23
|
|
|
18
24
|
# Route protection
|
|
25
|
+
# This app-owned starter config begins public-first; switch to True only when most routes require auth.
|
|
26
|
+
# Use all-private mode when only a few routes should stay public.
|
|
19
27
|
is_all_routes_private=False,
|
|
20
28
|
public_routes=["/"],
|
|
29
|
+
# Sign-in and signup stay public by default; only change this when the app explicitly needs it.
|
|
21
30
|
auth_routes=["/signin", "/signup"],
|
|
22
31
|
private_routes=[], # unused when all-routes-private is True
|
|
23
32
|
|