caspian-utils 0.0.6 → 0.0.8

package/dist/docs/commands.md

@@ -21,7 +21,7 @@ The current workspace includes a local `prisma` binary, but it does not include
 Use Caspian CLI commands for three main tasks:
 
 - Create a new application.
-- Generate code from your Prisma schema.
+- Regenerate Node and Python ORM code from your Prisma schema.
 - Update framework-managed project files.
 
 Before running update commands, review `caspian.config.json` because it controls overwrite behavior.
@@ -60,15 +60,23 @@ Common scaffold flags include:
 
 ## Code Generation
 
-When your Prisma schema changes in this workspace, regenerate the client with the local Prisma CLI:
+When `prisma/schema.prisma` changes in this workspace, use this command flow:
 
 ```bash
+npx prisma migrate dev
+
+# If the change requires refreshed seed data:
 npx prisma generate
+npx prisma db seed
+
+npx ppy generate
 ```
 
-This flow regenerates the Prisma client defined by `generator client` in `prisma/schema.prisma`. In the current workspace, that generator uses `prisma-client-js`.
+Use `npx prisma migrate dev` first so the development database and migration history stay aligned. If the updated schema affects seed data, run `npx prisma generate` before `npx prisma db seed` so Node-side tooling such as `prisma/seed.ts` uses the current generated client.
+
+Always finish with `npx ppy generate`. That is the required way to refresh the Python ORM classes used by the app after a schema change.
 
-This workspace already includes an app-owned Python database layer in `src/lib/prisma/`, so reuse that package for Python-side database access instead of creating a second helper.
+This workspace already includes an app-owned Python database layer in `src/lib/prisma/`, so reuse that package for Python-side database access instead of creating a second helper. Do not hand-edit generated ORM classes.
 
 See `database.md` for the full Prisma workflow, including `.env`, `prisma.config.ts`, migrations, and async usage patterns.
 
@@ -113,7 +121,10 @@ If an AI agent is deciding which command flow to use, apply these rules first.
 - Use `npx create-caspian-app@latest` when the user is creating a new project.
 - Use `npx casp update project` only for an existing Caspian project.
 - Read `caspian.config.json` before running update commands.
-- Use `npx prisma generate` after Prisma schema changes in this workspace.
+- When `prisma/schema.prisma` changes, run `npx prisma migrate dev` first.
+- If the change requires seed data, run `npx prisma generate` and then `npx prisma db seed`.
+- Run `npx ppy generate` after every Prisma schema change to refresh the Python ORM classes.
+- Never hand-edit generated Prisma or Python ORM classes.
 - Check `database.md` when the task involves Prisma setup, schema updates, or the current workspace's schema, migration, and seed tooling.
 - Check [routing.md](./routing.md) before generating or modifying route folders under `src/app/`.
 - Check [project-structure.md](./project-structure.md) before placing generated files into the project.

package/dist/docs/components.md

@@ -70,6 +70,8 @@ Treat `<!-- @import ... -->` as a file-level directive, not as rendered markup.
 - `<!-- @import Container from "../components" -->` resolves `Container.py` from that folder.
 - The component function name should match the tag name you render, such as `Container` for `<Container />`.
 - Grouped imports and aliases are also supported, for example `<!-- @import { Button, Card as UserCard } from "../components/ui" -->`.
+- If one Python file exports several `@component` functions, point `from` at that exact file instead of assuming one file per tag.
+- In that case, prefer one grouped import so every rendered tag resolves back to the same Python module.
 
 Good:
 
@@ -92,6 +94,38 @@ Bad:
 </section>
 ```
 
+### Same-File Component Exports
+
+Caspian does not require one Python file per component. A single file can export a main component plus related subcomponents.
+
+If `Breadcrumb.py` defines `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, and `BreadcrumbSeparator`, import those names from `Breadcrumb.py` itself.
+
+```html
+<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from "../maddex/Breadcrumb.py" -->
+
+<div class="dashboard-topbar">
+  <Breadcrumb class="dashboard-breadcrumbs" aria-label="Dashboard breadcrumbs">
+    <BreadcrumbList class="dashboard-breadcrumbs__list">
+      <BreadcrumbItem class="dashboard-breadcrumbs__item">
+        <BreadcrumbLink href="/dashboard">Dashboard</BreadcrumbLink>
+      </BreadcrumbItem>
+      <BreadcrumbSeparator class="dashboard-breadcrumbs__separator" />
+      <BreadcrumbItem class="dashboard-breadcrumbs__item">
+        <BreadcrumbPage class="dashboard-breadcrumbs__page">Reports</BreadcrumbPage>
+      </BreadcrumbItem>
+    </BreadcrumbList>
+  </Breadcrumb>
+</div>
+```
+
+If you only need one component from that file, keep the same file path:
+
+```html
+<!-- @import Breadcrumb from "../maddex/Breadcrumb.py" -->
+```
+
+Do not invent folder-level imports for symbols that do not have their own file. If `BreadcrumbItem` lives inside `Breadcrumb.py`, import it from `Breadcrumb.py`, not from `../maddex` as if `BreadcrumbItem.py` existed.
+
 ## Template-Backed Components
 
 When a component includes richer UI or PulsePoint behavior, keep the Python file focused on props or server-side preparation and move the markup into a same-name HTML file.

package/dist/docs/database.md

@@ -22,9 +22,10 @@ The standard Prisma flow in Caspian is:
 
 1. Define models in `prisma/schema.prisma`.
 2. Configure `DATABASE_URL` in `.env`.
-3. Run `npx prisma generate` after schema changes.
-4. Use the generated client from Node-side tooling such as `prisma/seed.ts`.
-5. Reuse the shared Python database layer in `src/lib/prisma/` when Python route or RPC code needs database access.
+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`.
+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. Drop to raw SQL only when a query cannot be expressed clearly with the generated client.
 
@@ -99,22 +100,30 @@ model Post {
 }
 ```
 
-After changing the schema, run `npx prisma generate` so the generated Node Prisma client stays in sync with the schema. If the Python layer in `src/lib/prisma/` depends on the updated shape, regenerate or refresh that application-owned code too.
+After changing the schema, use this order in the current workspace:
+
+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`.
+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.
 
 ## Command Reference
 
 Use these commands for the normal Prisma lifecycle in Caspian:
 
-- `npx prisma generate` compiles `schema.prisma` into the generated Prisma client. Run this after every schema change.
-- `npx prisma migrate dev` creates and applies a development migration.
+- `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 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.
-- `npx prisma db seed` runs the configured seeding script.
 - `npx prisma studio` opens the Prisma data browser.
 
 Default rule:
 
-- Use `npx prisma generate` every time the schema changes.
+- 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`.
+- 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.
 
@@ -142,7 +151,7 @@ After `npx prisma generate`, Prisma writes the generated JavaScript client into
 
 This workspace already includes an app-owned async Python database package that exports `prisma`, `PrismaClient`, generated models, and helper types.
 
-If Python route or RPC code needs database access, import from `src.lib.prisma` and keep that import path explicit in application code.
+If Python route or RPC code needs database access, import from `src.lib.prisma` and keep that import path explicit in application code. Refresh generated classes with `npx ppy generate` instead of editing them manually.
 
 ## Python Route Usage
 
@@ -306,8 +315,9 @@ Use raw SQL sparingly. Prefer the generated Prisma API when the query can be exp
 
 ## Recommended Project Rules
 
-- Keep the schema in `prisma/schema.prisma` and regenerate the client after changes.
+- 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.
+- 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.
@@ -320,7 +330,10 @@ 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.
-- Run `npx prisma generate` after schema 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`.
+- 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 workspace's Prisma tooling examples.
 - Reuse the existing `src/lib/prisma/` package when the Python app needs database access.
 - Put reusable database helpers in `src/lib/`; keep route and RPC orchestration in `src/app/`.

package/dist/docs/index.md

@@ -58,7 +58,7 @@ Preferred lookup order:
 1. Read `node_modules/caspian-utils/dist/docs/index.md` to discover available local docs.
 2. Read `./caspian.config.json` before making any feature assumption. Use it to confirm which project capabilities are enabled and which directories or tooling rules apply.
 3. Read `database.md` for Prisma setup and ORM usage, `auth.md` for session auth and route protection, `components.md` for reusable UI authoring, `pulsepoint.md` for browser-side reactive runtime behavior, `fetch-data.md` for data flows, `state.md` for transient request-scoped state, `cache.md` for page caching, and `validation.md` for input boundaries.
-4. For authored component, route, and layout HTML files, generate exactly one top-level lowercase HTML element. Think React-style single parent wrapper: keep any owned PulsePoint logic in a plain `<script>` inside that root, do not handwrite `pp-component="..."` or `type="text/pp"` because Caspian injects those runtime attributes automatically, and treat `<!-- @import ... -->` comments as file-level directives that belong above the authored root element instead of inside `<div>`, `<section>`, or `<html>`.
+4. For authored component, route, and layout HTML files, generate exactly one top-level lowercase HTML element. Think React-style single parent wrapper: keep any owned PulsePoint logic in a plain `<script>` inside that root, do not handwrite `pp-component="..."` or `type="text/pp"` because Caspian injects those runtime attributes automatically, and treat `<!-- @import ... -->` comments as file-level directives that belong above the authored root element instead of inside `<div>`, `<section>`, or `<html>`. When several component tags come from one Python file, import them from that exact file path, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`.
 5. Prefer local docs before generating code, commands, or migration guidance.
 6. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
 7. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.

package/dist/docs/project-structure.md

@@ -98,6 +98,8 @@ Use this folder for reusable UI components that should be imported into route te
 
 The common Caspian pattern is a Python file such as `Button.py` with `@component`, optionally paired with a same-name HTML file such as `Button.html` when the component has richer markup or PulsePoint behavior.
 
+One Python file can also export multiple related `@component` functions. When that happens, import those tags from that exact file path in HTML, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`, instead of assuming each tag has its own sibling `.py` file.
+
 For component HTML files, follow the same one-parent rule as route HTML files: one top-level lowercase HTML element only, with no sibling roots and no top-level script sitting outside that root.
 
 Do not handwrite `pp-component="..."` or `type="text/pp"` in component source templates either. Write plain `<script>` inside the single root and let the render pipeline inject the runtime shape.

package/package.json

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