create-caspian-app 0.2.0-beta.38 → 0.2.0-beta.39

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

@@ -28,6 +28,8 @@
 - In all-private mode, keep public exceptions in `public_routes`; the runtime defaults keep `/` public and keep `auth_routes=["/signin", "/signup"]` public.
 - 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.
 - Use PulsePoint and `pp.rpc(...)` as the default frontend and client-to-server contract unless the user requests another stack.
+- 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/storage/**`.
+- When runtime uploads write into `public/storage/**`, keep `public/storage` in `settings/bs-config.ts` `PUBLIC_IGNORE_DIRS` so `npm run dev` does not reload on each upload.
 - 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.
 - 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`.
 - 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.
@@ -42,6 +44,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`.
+- Do not move normal file upload or file-manager behavior into `main.py`; keep those actions in the owning route `index.py` and shared helpers in `src/lib/**`.
 - 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.
 
@@ -50,6 +53,7 @@
 - Keep `src/lib/` for app-owned shared non-UI code, service wrappers, validators, adapters, and reusable helpers.
 - Prefer `src/components/` for reusable rendered UI instead of placing component modules in `src/lib/`.
 - 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.
+- For file managers, keep shared storage, normalization, and Prisma-backed persistence helpers here while route-owned upload and delete `@rpc()` actions stay in `src/app/**/index.py`.
 - 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.
 - Keep auth policy in `src/lib/auth/auth_config.py`. Keep auth bootstrap and middleware order changes in `main.py`.
 
@@ -78,6 +82,7 @@
 - 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.
+- For upload managers and similar interactive lists, prefer `pp.state(...)` plus `pp-for` over manual DOM painting so rerenders keep the list stable.
 - Do not assume React, Vue, JSX, HTMX, or another frontend runtime unless the user explicitly requests one.
 
 ### `prisma/**`
@@ -112,6 +117,8 @@
   - 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
   - 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`
   - `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
+  - `node_modules/caspian-utils/dist/docs/file-uploads.md` is the source doc for route-local upload and file-manager guidance in this workspace
+  - uploaded public blobs live under `public/storage/**`, and `settings/bs-config.ts` should keep `public/storage` in `PUBLIC_IGNORE_DIRS`
   - `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
   - auth policy lives in `src/lib/auth/auth_config.py`
   - 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

package/dist/AGENTS.md

@@ -59,15 +59,17 @@ Treat `caspian.config.json` as the single source of truth for whether an optiona
 - `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>`.
+- 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/storage/**`.
 - 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.
 - `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.
+- `settings/bs-config.ts` should keep `public/storage` in `PUBLIC_IGNORE_DIRS` so runtime uploads do not trigger BrowserSync reloads during the local stack.
 - 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.
+- The current app tree has root templates in `src/app/` and already includes route-specific `index.py` files where routes need server-side logic, including upload and file-manager flows.
 
 ## Task Routing
 
@@ -81,6 +83,7 @@ Use this map before making changes.
 | 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`  |
+| File uploads and managers                 | `node_modules/caspian-utils/dist/docs/file-uploads.md`, `node_modules/caspian-utils/dist/docs/fetch-data.md` | `src/app/**`, `src/lib/**`, `prisma/**`, `settings/bs-config.ts`                 |
 | 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`                                       |
@@ -91,6 +94,7 @@ Use this map before making changes.
 - Keep app-owned shared code in `src/lib/**`.
 - Keep reusable application UI components in `src/components/**`.
 - Keep route-specific logic in `src/app/**`.
+- 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/**`, and keep uploaded public blobs under `public/storage/**`.
 - 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/**`.
 - Read `caspian.config.json` before deciding whether a Caspian feature should be used, documented, scaffolded, or avoided in the current workspace.
 - 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.
@@ -125,6 +129,7 @@ The packaged docs in this workspace are already mostly aligned with the installe
 
 - `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.
 - `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.
+- `file-uploads.md` is the source doc for route-local uploads and file-manager flows in this repo: keep upload and delete RPCs in the owning route `index.py`, keep shared storage plus Prisma helpers in `src/lib/**`, store browser-accessible blobs under `public/storage/**`, and keep that directory in `settings/bs-config.ts` `PUBLIC_IGNORE_DIRS`.
 - 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.
 - `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.
 - `state.md` is correct to warn that cross-request persistence depends on `request.state.session`, which is not bridged in the current `main.py`.

package/dist/settings/bs-config.ts

@@ -18,6 +18,7 @@ import caspianConfig from "../caspian.config.json";
 const { __dirname } = getFileMeta();
 const bs: BrowserSyncInstance = browserSync.create();
 
+const WORKSPACE_ROOT = join(__dirname, "..");
 const PUBLIC_IGNORE_DIRS = [""];
 let previousRouteFiles: string[] = [];
 let lastChangedFile: string | null = null;
@@ -32,7 +33,14 @@ function getReservedPorts(): Set<number> {
     return reservedPorts;
   }
 
-  const mcpSpecPath = join(__dirname, "..", "src", "lib", "mcp", "fastmcp.json");
+  const mcpSpecPath = join(
+    __dirname,
+    "..",
+    "src",
+    "lib",
+    "mcp",
+    "fastmcp.json",
+  );
   if (!existsSync(mcpSpecPath)) {
     return reservedPorts;
   }
@@ -159,6 +167,14 @@ function updateRouteFilesCache() {
   }
 }
 
+function isIgnoredPublicPath(absPath: string): boolean {
+  const normalizedPath = relative(WORKSPACE_ROOT, absPath).replace(/\\/g, "/");
+
+  return PUBLIC_IGNORE_DIRS.some(
+    (dir) => normalizedPath === dir || normalizedPath.startsWith(`${dir}/`),
+  );
+}
+
 const publicPipeline = new DebouncedWorker(
   async () => {
     console.log(chalk.cyan("→ Public directory changed, reloading browser..."));
@@ -191,8 +207,7 @@ const publicPipeline = new DebouncedWorker(
   createSrcWatcher(join(PUBLIC_DIR, "**", "*"), {
     onEvent: (_ev, abs, _) => {
       const relFromPublic = relative(PUBLIC_DIR, abs);
-      const normalized = relFromPublic.replace(/\\/g, "/");
-      if (PUBLIC_IGNORE_DIRS.includes(normalized.split("/")[0])) return;
+      if (isIgnoredPublicPath(abs)) return;
       publicPipeline.schedule(relFromPublic);
     },
     awaitWriteFinish: DEFAULT_AWF,

package/package.json

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