caspian-utils 0.1.11 → 0.1.12

package/dist/docs/commands.md

@@ -105,6 +105,7 @@ npx prisma migrate dev
 
 # If the change requires refreshed seed data:
 npx prisma generate
+# Destructive-data warning: ask the user for explicit approval before running this.
 npx prisma db seed
 
 npx ppy generate
@@ -112,6 +113,8 @@ npx ppy generate
 
 Use when `prisma/schema.prisma` changes and you need migrations, seed flow, and the generated Python ORM layer to stay aligned.
 
+`npx prisma db seed` is a delicate operation because the configured seed script may clean tables or replace existing rows before inserting seed data. Before running it, an AI agent must say the exact command it plans to run, warn that it can delete or overwrite database data, confirm the active datasource when practical, and wait for explicit user approval.
+
 ## 2. Script Guardrails
 
 - Before using an optional feature, confirm its flag in `caspian.config.json`.
@@ -179,12 +182,12 @@ In skip-prompt mode, the default feature values are:
 
 - `backendOnly: false`
 - `tailwindcss: false`
-- `typescript: false`
-- `mcp: false`
-- `prisma: false`
-- `websocket: false`
-
-If a project needs WebSockets after creation, set `websocket: true` in `caspian.config.json`, then run the project update workflow so framework-managed files and any scaffolded socket surfaces stay aligned before assuming `@app.websocket(...)` routes or `src/lib/websocket/**` exist.
+- `typescript: false`
+- `mcp: false`
+- `prisma: false`
+- `websocket: false`
+
+If a project needs WebSockets after creation, set `websocket: true` in `caspian.config.json`, then run the project update workflow so framework-managed files and any scaffolded socket surfaces stay aligned before assuming `@app.websocket(...)` routes or `src/lib/websocket/**` exist.
 
 ### 4.2 Backend-only combinations
 
@@ -597,6 +600,7 @@ npx prisma migrate dev
 
 # Only when seed flow or prisma/seed.ts depends on the new schema:
 npx prisma generate
+# Destructive-data warning: ask the user for explicit approval before running this.
 npx prisma db seed
 
 npx ppy generate
@@ -605,7 +609,7 @@ npx ppy generate
 Use this order:
 
 1. Run `npx prisma migrate dev` first so migrations and the development database stay aligned.
-2. If `prisma/seed.ts` or seed data depends on the new schema, run `npx prisma generate` and then `npx prisma db seed`.
+2. If `prisma/seed.ts` or seed data depends on the new schema, run `npx prisma generate`, then request explicit user approval before running `npx prisma db seed` because the seed script may delete or overwrite database data.
 3. Run `npx ppy generate` last so the generated Python ORM layer matches the updated Prisma schema.
 
 Do not manually create or edit these generated files:
@@ -678,7 +682,7 @@ If an AI agent is deciding which command flow to use, apply these rules first.
 - Treat `--tailwindcss` and `--typescript` as frontend-oriented flags. They are not meaningful in normal backend-only scaffolds.
 - Treat starter kit defaults as a base layer that can be overridden by explicit flags.
 - Read `caspian.config.json` before running update commands.
-- When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first, then any required seed refresh, then `npx ppy generate`.
+- When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first, then any required seed refresh, then `npx ppy generate`. Before running `npx prisma db seed`, warn the user that it can delete or overwrite data and wait for explicit approval.
 - Never hand-edit generated Python ORM files under `src/lib/prisma/` or `settings/prisma-schema.json`.
 - Read [database.md](./database.md) before generating Prisma schema, migration, seed, or ORM guidance.
 - Read [routing.md](./routing.md) before generating or modifying route folders under `src/app/`.

package/dist/docs/database.md

@@ -14,9 +14,9 @@ related:
 
 This page documents the Prisma workflow for Caspian projects where `caspian.config.json` enables Prisma.
 
-When a project enables Prisma, use `prisma/schema.prisma` for schema management, `prisma.config.ts` for Prisma config and seed wiring, and reuse an app-owned `src/lib/prisma/` package when the project includes one.
-
-High-priority rule: when `caspian.config.json` has `prisma: true`, Python-side database access must use the generated Prisma Python ORM. Route `page()` functions, route-owned `@rpc()` actions, auth handlers, upload flows, and shared helpers should import the generated client from `src/lib/prisma/**` instead of inventing direct driver calls, hand-written SQL wrappers, JSON manifests as active stores, app-specific HTTP fetches, or browser-side database fetches. For normal reads and writes, default to Prisma methods such as `find_many`, `find_unique`, `create`, `update`, `delete`, `delete_many`, aggregates, includes, and transactions. Use raw SQL only through Prisma as a narrow fallback when the generated ORM cannot express a query clearly, and treat that fallback as provider-specific code that may break when a project moves between SQLite, MySQL, and PostgreSQL.
+When a project enables Prisma, use `prisma/schema.prisma` for schema management, `prisma.config.ts` for Prisma config and seed wiring, and reuse an app-owned `src/lib/prisma/` package when the project includes one.
+
+High-priority rule: when `caspian.config.json` has `prisma: true`, Python-side database access must use the generated Prisma Python ORM. Route `page()` functions, route-owned `@rpc()` actions, auth handlers, upload flows, and shared helpers should import the generated client from `src/lib/prisma/**` instead of inventing direct driver calls, hand-written SQL wrappers, JSON manifests as active stores, app-specific HTTP fetches, or browser-side database fetches. For normal reads and writes, default to Prisma methods such as `find_many`, `find_unique`, `create`, `update`, `delete`, `delete_many`, aggregates, includes, and transactions. Use raw SQL only through Prisma as a narrow fallback when the generated ORM cannot express a query clearly, and treat that fallback as provider-specific code that may break when a project moves between SQLite, MySQL, and PostgreSQL.
 
 Treat `caspian.config.json` as the single source of truth for whether Prisma is enabled in a workspace. If `prisma` is false and the user wants Prisma, ask first, then update `caspian.config.json` and run `npx casp update project` before assuming Prisma-managed files exist.
 
@@ -27,11 +27,25 @@ The standard Prisma flow in Caspian is:
 1. Define models in `prisma/schema.prisma`.
 2. Configure `DATABASE_URL` in `.env`.
 3. Run `npx prisma migrate dev` after schema changes so the development database and migration history stay aligned.
-4. If the change requires seed data, run `npx prisma generate` and then `npx prisma db seed`.
+4. If the change requires seed data, run `npx prisma generate`, then request explicit user approval before running `npx prisma db seed`.
 5. Run `npx ppy generate` so the Python ORM classes stay aligned with the updated schema.
 6. Reuse the shared Python database layer in `src/lib/prisma/` when Python route or RPC code needs database access, and never hand-edit generated ORM classes.
 
-Use this workflow instead of writing raw SQL first. For normal CRUD and relation work, stay on the generated Prisma API. Drop to raw SQL only through Prisma when a query cannot be expressed clearly with the generated client, and assume that raw SQL requires extra review for cross-database portability.
+Use this workflow instead of writing raw SQL first. For normal CRUD and relation work, stay on the generated Prisma API. Drop to raw SQL only through Prisma when a query cannot be expressed clearly with the generated client, and assume that raw SQL requires extra review for cross-database portability.
+
+## Seed Command Safety
+
+Treat `npx prisma db seed` as a destructive data operation, not as a routine regeneration command. A project's `prisma/seed.ts` may delete existing rows, reset lookup tables, replace users, or otherwise rewrite the current datasource before inserting seed data. If `DATABASE_URL` points at a shared, staging, or production database, running the seed command can delete production information.
+
+Before any AI agent runs `npx prisma db seed`, it must:
+
+1. Read `prisma.config.ts` and `prisma/seed.ts` to understand what the seed command will execute.
+2. State the exact command it intends to run: `npx prisma db seed`.
+3. Warn the user clearly that the command can delete or overwrite database data.
+4. Confirm the active datasource or `DATABASE_URL` when practical, without exposing secrets.
+5. Wait for explicit user approval before executing the command.
+
+Do not run `npx prisma db seed` merely because it appears in the standard workflow. Ask first, and only continue after the user has approved that specific seed operation.
 
 ## Environment Setup
 
@@ -49,7 +63,7 @@ Example for PostgreSQL in async-friendly production environments:
 DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
 ```
 
-For most local development, SQLite is the simplest starting point. For production or higher concurrency workloads, prefer PostgreSQL or MySQL. Regardless of the starting provider, keep application queries on the Prisma ORM whenever possible so schema and query behavior stay easier to migrate across providers.
+For most local development, SQLite is the simplest starting point. For production or higher concurrency workloads, prefer PostgreSQL or MySQL. Regardless of the starting provider, keep application queries on the Prisma ORM whenever possible so schema and query behavior stay easier to migrate across providers.
 
 ## Global Prisma Configuration
 
@@ -107,7 +121,7 @@ model Post {
 After changing the schema, use this order:
 
 1. Run `npx prisma migrate dev`.
-2. If seed data or the seed script needs the new schema, run `npx prisma generate` and then `npx prisma db seed`.
+2. If seed data or the seed script needs the new schema, run `npx prisma generate`, then request explicit user approval before running `npx prisma db seed`.
 3. Run `npx ppy generate` to refresh the generated Python ORM classes.
 
 Do not hand-edit generated Prisma or Python ORM output. Treat `prisma/schema.prisma` as the source of truth and regenerate from it.
@@ -118,7 +132,7 @@ Use these commands for the normal Prisma lifecycle in Caspian:
 
 - `npx prisma migrate dev` creates and applies a development migration. This is the first command to run after changing `prisma/schema.prisma`.
 - `npx prisma generate` compiles `schema.prisma` into the generated Node Prisma client. Run it before `npx prisma db seed` when the updated seed flow depends on the new schema.
-- `npx prisma db seed` runs the configured seeding script.
+- `npx prisma db seed` runs the configured seeding script. This may delete or overwrite existing database data; an AI agent must warn the user and receive explicit approval before executing it.
 - `npx ppy generate` regenerates the Python ORM classes used by the app. Use this after every schema change.
 - `npx prisma migrate deploy` applies pending migrations in deployment environments.
 - `npx prisma db push` syncs schema changes without creating a migration file, which is useful for prototyping.
@@ -126,7 +140,7 @@ Use these commands for the normal Prisma lifecycle in Caspian:
 
 Default rule:
 
-- When `prisma/schema.prisma` changes, use this order: `npx prisma migrate dev`; if seeding is involved, run `npx prisma generate` and `npx prisma db seed`; then run `npx ppy generate`.
+- When `prisma/schema.prisma` changes, use this order: `npx prisma migrate dev`; if seeding is involved, run `npx prisma generate`, ask for explicit approval before `npx prisma db seed`, then run `npx ppy generate`.
 - Never hand-edit generated Prisma or Python ORM classes, and never replace `npx ppy generate` with a manual class update.
 - Use migrations for tracked application changes.
 - Use `db push` only when you intentionally want a faster, migration-free prototype loop.
@@ -159,7 +173,7 @@ If Python route or RPC code needs database access, import from `src.lib.prisma`
 
 ## Python Route Usage
 
-If the project ships an app-owned Python Prisma-style layer under `src/lib/prisma/`, treat it as async-first and reuse it from route and RPC code. In a Prisma-enabled project, this is the required data-access path for Python code.
+If the project ships an app-owned Python Prisma-style layer under `src/lib/prisma/`, treat it as async-first and reuse it from route and RPC code. In a Prisma-enabled project, this is the required data-access path for Python code.
 
 Example:
 
@@ -180,7 +194,7 @@ Prisma calls fit naturally in:
 - `async def page()` for first-render data
 - `@rpc()` actions for browser-triggered reads and writes
 
-Keep route-specific Prisma I/O in that route's `page()` or `@rpc()` actions in `src/app/**/index.py`. The installed layout engine supports synchronous and async `layout()` results, but layout work should stay focused on shared subtree props or metadata. Move Prisma helpers into `src/lib/**` only when the same behavior is reused by multiple routes, features, or integrations.
+Keep route-specific Prisma I/O in that route's `page()` or `@rpc()` actions in `src/app/**/index.py`. The installed layout engine supports synchronous and async `layout()` results, but layout work should stay focused on shared subtree props or metadata. Move Prisma helpers into `src/lib/**` only when the same behavior is reused by multiple routes, features, or integrations.
 
 See `fetch-data.md` for the recommended route-render versus RPC split.
 
@@ -318,39 +332,39 @@ async with prisma.transaction() as tx:
     )
 ```
 
-### Raw SQL Fallback
-
-Use this escape hatch sparingly. Raw SQL is not the default query style in a Prisma-enabled Caspian project.
-
-Before using `query_raw()` or `execute_raw()`, confirm that the generated Prisma API cannot express the query clearly with normal methods such as `find_many`, `find_unique`, `create`, `update`, `delete`, `delete_many`, `aggregate`, relation `include`, or transactions.
-
-Important portability warning:
-
-- Raw SQL is provider-specific. Placeholder style, identifier quoting, JSON operators, case-sensitivity rules, date functions, and aggregate behavior can differ across SQLite, MySQL, and PostgreSQL.
-- A raw query that works in SQLite may fail after a move to PostgreSQL or MySQL even when the Prisma schema migrates cleanly.
-- If a project may switch providers, prefer Prisma ORM methods first and treat raw SQL as an exception that needs provider-aware review.
-
-```python
-users = await prisma.user.find_many(
-    where={
-        "email": {"contains": "@gmail.com"},
-    },
-)
-```
-
-If raw SQL is still unavoidable, keep it tightly scoped, document why the ORM was insufficient, and verify it against the current datasource provider in `prisma/schema.prisma`.
+### Raw SQL Fallback
+
+Use this escape hatch sparingly. Raw SQL is not the default query style in a Prisma-enabled Caspian project.
+
+Before using `query_raw()` or `execute_raw()`, confirm that the generated Prisma API cannot express the query clearly with normal methods such as `find_many`, `find_unique`, `create`, `update`, `delete`, `delete_many`, `aggregate`, relation `include`, or transactions.
+
+Important portability warning:
+
+- Raw SQL is provider-specific. Placeholder style, identifier quoting, JSON operators, case-sensitivity rules, date functions, and aggregate behavior can differ across SQLite, MySQL, and PostgreSQL.
+- A raw query that works in SQLite may fail after a move to PostgreSQL or MySQL even when the Prisma schema migrates cleanly.
+- If a project may switch providers, prefer Prisma ORM methods first and treat raw SQL as an exception that needs provider-aware review.
+
+```python
+users = await prisma.user.find_many(
+    where={
+        "email": {"contains": "@gmail.com"},
+    },
+)
+```
+
+If raw SQL is still unavoidable, keep it tightly scoped, document why the ORM was insufficient, and verify it against the current datasource provider in `prisma/schema.prisma`.
 
 ## Recommended Project Rules
 
 - Keep the schema in `prisma/schema.prisma` and follow the required regeneration order after changes: `npx prisma migrate dev`, optional seed flow, then `npx ppy generate`.
-- Reuse `src/lib/prisma/` for Python-side database access instead of creating a second bridge.
-- When Prisma is enabled, do not bypass the Prisma Python ORM with direct database drivers, custom fetch functions, JSON files as active stores, or browser-side database access.
+- Reuse `src/lib/prisma/` for Python-side database access instead of creating a second bridge.
+- When Prisma is enabled, do not bypass the Prisma Python ORM with direct database drivers, custom fetch functions, JSON files as active stores, or browser-side database access.
 - Never hand-edit generated Prisma or Python ORM classes.
 - Keep reusable database helpers in `src/lib/`, and keep route-specific orchestration in `src/app/`.
 - Use `await` with Prisma operations.
 - Convert Prisma objects to template-safe dictionaries when rendering HTML.
 - Validate incoming mutation data before calling `create`, `update`, or `delete` operations.
-- Prefer Prisma queries over raw SQL. If raw SQL is unavoidable, keep it provider-aware, narrowly scoped, and documented so future database-provider migrations do not silently break application behavior.
+- Prefer Prisma queries over raw SQL. If raw SQL is unavoidable, keep it provider-aware, narrowly scoped, and documented so future database-provider migrations do not silently break application behavior.
 
 ## AI Retrieval Notes
 
@@ -359,13 +373,13 @@ If an AI agent is working on a Caspian app with Prisma enabled, apply these rule
 - Treat Prisma as the default ORM and persistence layer.
 - Read `prisma/schema.prisma` before proposing model, relation, or field changes.
 - When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first.
-- If the schema change requires seed data, run `npx prisma generate` and then `npx prisma db seed`.
+- If the schema change requires seed data, run `npx prisma generate`, then request explicit user approval before running `npx prisma db seed`.
 - Run `npx ppy generate` after schema changes to refresh the Python ORM classes.
 - Never hand-edit generated Prisma or Python ORM classes.
 - Read `prisma.config.ts` and `prisma/seed.ts` when you need the current project's Prisma tooling examples.
-- Reuse the existing `src/lib/prisma/` package when the Python app needs database access.
-- Treat use of the Prisma Python ORM as mandatory for Python-side database reads and writes in Prisma-enabled projects.
+- Reuse the existing `src/lib/prisma/` package when the Python app needs database access.
+- Treat use of the Prisma Python ORM as mandatory for Python-side database reads and writes in Prisma-enabled projects.
 - For file managers and uploads, persist metadata in Prisma and keep blob storage separate. See [file-uploads.md](./file-uploads.md).
 - Put reusable database helpers in `src/lib/`; keep route and RPC orchestration in `src/app/`.
-- Use `async def page()` for route-specific first-render reads. Use `layout()` only for shared subtree props or metadata, and use `@rpc()` plus `pp.rpc()` for browser-triggered reads and writes.
+- Use `async def page()` for route-specific first-render reads. Use `layout()` only for shared subtree props or metadata, and use `@rpc()` plus `pp.rpc()` for browser-triggered reads and writes.
 - Check `fetch-data.md` for route versus RPC guidance and `validation.md` before writing public mutations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caspian-utils",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {