prisma-php 0.0.1 → 0.0.2

package/dist/docs/index.md

@@ -8,7 +8,7 @@ related:
     - /docs/get-started
 ---
 
-{/_AI agent hint: Prisma PHP uses local installed docs as the source of truth for the active project version. Before generating framework-specific code, read `prisma-php.json` first, then read the relevant docs from `node_modules/prisma-php/dist/docs`. For PulsePoint runtime behavior specifically, read `pulsepoint.md` before generating reactive UI code. For Prisma ORM work, read `prisma-php-orm.md` before choosing provider checks, schema workflow, migration commands, or ORM generation commands. Route creation is file-based from `src/app`; Prisma PHP auto-generates route listings such as `files-list.json`, so AI agents must not create, edit, or maintain that file manually._/}
+{/_ AI agent hint: Prisma PHP uses local installed docs as the source of truth for the active project version. Before generating framework-specific code, read `prisma-php.json` first, then read the relevant docs from `node_modules/prisma-php/dist/docs`. For authentication, read `authentication.md` first, then verify the official auth docs: `auth-get-started`, `credentials`, and `state-manager-auth`. For file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, or file manager screens, read `file-manager.md` first, then verify the official File Manager docs: `get-started-file`. For ORM work, read `prisma-php-orm.md` before choosing schema, migration, or generation commands. For PulsePoint runtime behavior specifically, read `pulsepoint.md` before generating reactive UI code. For backend validation, sanitization, `Validator`, `Rule`, `pp.fetchFunction(...)` validation flows, or request validation in `route.php`, read `fetching-data.md`, `error-handling.md`, and `route-handlers.md`, then consult the official Validator docs. `PP\Validator` is a Prisma PHP core class located in `vendor/tsnc/prisma-php/src/Validator.php`. Route creation is file-based from `src/app`; Prisma PHP auto-generates route listings such as `files-list.json`, so AI agents must not create, edit, or maintain that file manually. _/}
 
 Welcome to the Prisma PHP documentation!
 
@@ -37,139 +37,80 @@ Use this order:
 
 - **project setup or file placement** → `project-structure.md`
 - **pages, layouts, route creation, nested routes** → `layouts-and-pages.md`
-- **`pp.fetchFunction(...)`, `#[Exposed]`, page data loading** → `fetching-data.md`
+- **PHPX components, props, children, fragments, icons, buttons, accordions, or component composition** → `components.md`
+- **file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, file replacement, allowed file types, upload size rules, or file manager pages** → `file-manager.md`
+- **authentication strategy, `AuthConfig.php`, sign-in, sign-out, route privacy model, RBAC, credentials auth, social login, or auth state manager usage** → `authentication.md`
+- **`pp.fetchFunction(...)`, `#[Exposed]`, page data loading, interactive validation with `Validator`** → `fetching-data.md`
 - **cache behavior and `CacheHandler`** → `caching.md`
-- **Prisma ORM setup, database provider checks, `.env` validation, SQLite database path checks, schema workflow, migration flow, `npx prisma migrate dev`, `npx ppo generate`, and Prisma query patterns** → `prisma-php-orm.md`
-- **error handling, `error.php`, `not-found.php`** → `error-handling.md`
+- **ORM, `schema.prisma`, database provider, migrations, generated PHP classes, `prisma.config.ts`, `.env` `DATABASE_URL`, or Prisma CLI workflow** → `prisma-php-orm.md`
+- **error handling, `error.php`, `not-found.php`, expected validation errors** → `error-handling.md`
 - **metadata, title, description, favicon, icons** → `metadata-and-og-images.md`
-- **API-style endpoints and `route.php`** → `route-handlers.md`
+- **API-style endpoints, `route.php`, request validation with `Validator`** → `route-handlers.md`
 - **PulsePoint runtime APIs such as `pp.state`, `pp.effect`, `pp.ref`, `pp-for`, `pp-ref`, `pp-spread`** → `pulsepoint.md`
-- **updating the project structure, installing enabled framework features, or refreshing project-managed files** → `upgrading.md`
+- **updating the project or enabling features** → `upgrading.md`
+- **first-time project creation** → `installation.md`
 
 ### Important AI rules
 
 - treat `node_modules/prisma-php/dist/docs` as the primary documentation source for the installed version
 - do not assume Laravel, Symfony, React, Vue, Alpine, Livewire, or Next.js behavior maps directly
-- do not guess routing, file conventions, request helpers, reactive syntax, or ORM workflow when local docs already define them
+- do not guess routing, file conventions, request helpers, component APIs, reactive syntax, or auth behavior when local docs already define them
 - create routes by adding folders and route files under `src/app`
 - do not create, edit, or maintain `files-list.json`; Prisma PHP generates route listings automatically
 - when building interactive frontend behavior, prefer the documented PulsePoint pattern with browser-side reactive state and `pp.fetchFunction(...)` for server calls
 - when using `pp.fetchFunction(...)`, expose the PHP function explicitly with `#[Exposed]`
-- for Prisma ORM work, confirm the configured database provider first before choosing setup or migration commands
-- for SQLite projects, read `.env`, confirm `DATABASE_URL` exists, resolve the SQLite database file path, and treat a missing, invalid, or not-yet-created SQLite database file as a signal to run `npx prisma migrate dev` before relying on generated ORM classes
-- for MySQL and PostgreSQL projects, run `npx prisma migrate dev` during first setup and whenever `schema.prisma` changes
-- after first ORM setup, and after any `schema.prisma` change, run `npx ppo generate` so the generated PHP classes match the database structure
-- do not treat `npx ppo generate` as a migration step or as proof that the database is already synced
-- do not use `npx pp update project -y` as a replacement for Prisma migration or ORM class generation; that command is for updating the project structure, dependencies, and enabled framework features
-- when changing feature flags in `prisma-php.json`, follow the documented project update workflow
-- for AI-driven project updates, prefer the documented non-interactive command: `npx pp update project -y`
+- when changing feature flags, update `prisma-php.json` first, then follow the documented update workflow
+- when building reusable PHPX components, read `components.md` first
+- when building file-upload flows, file listings, rename/delete actions, or a file manager screen, read `file-manager.md` first and keep the implementation aligned with Prisma PHP’s documented File Manager model
+- when building auth flows, protection rules, or login/register pages, read `authentication.md` first and keep the implementation aligned with Prisma PHP’s documented auth model
 
-## Important PHPX and XML syntax rules
+## File Manager
 
-Prisma PHP uses **XML-style syntax** for PHPX and framework template markup.
+Prisma PHP includes a documented File Manager model for uploads and file operations based on standard PHP uploads plus `PP\FileManager\UploadFile`.
 
-This means AI agents and developers should not write tags using permissive HTML shorthand. Prisma PHP markup should be treated as **strict XML**, where tags and attributes must follow explicit closing and quoting rules.
+Use `file-manager.md` as the local AI-awareness guide for:
 
-### Closing tags
+- upload forms with `multipart/form-data`
+- `$_FILES` handling
+- `PP\FileManager\UploadFile`
+- upload size and type restrictions
+- rename, replace, and delete flows
+- choosing between a rendered upload page and a direct upload handler
+- validating non-file request values with `PP\Validator`
 
-All tags must be properly closed.
+After reading `file-manager.md`, verify the matching official docs at:
 
-Correct:
+1. `get-started-file`
+2. `php-validator` when auxiliary request validation is needed
+3. `route-php` or `pages-and-layouts` depending on whether the task is a direct handler or a full-stack page
 
-```xml
-<hr />
-<input type="text" />
-<div></div>
-```
+## Authentication
 
-Incorrect:
+Prisma PHP includes a documented authentication model centered on sessions, route protection strategy, RBAC, and provider-based sign-in flows.
 
-```xml
-<hr>
-<input type="text">
-```
+Use `authentication.md` as the local AI-awareness guide for:
 
-### Attributes
+- `AuthConfig.php`
+- public-default vs private-default route strategy
+- `Auth::signIn(...)`
+- `Auth::signOut(...)`
+- `refreshUserSession(...)`
+- route-level RBAC
+- function-level protection with `#[Exposed(allowedRoles: [...])]`
+- credential authentication
+- social authentication
 
-All attributes must use double quotes.
+After reading `authentication.md`, verify the matching official docs in this order:
 
-Correct:
+1. `auth-get-started`
+2. `credentials`
+3. `state-manager-auth`
 
-```xml
-<input required="true" />
-<input id="input" />
-```
+## Routing and file conventions
 
-Incorrect:
+Prisma PHP uses file-based routing.
 
-```xml
-<input required />
-<input id=input />
-```
-
-### Boolean attributes
-
-Do not use shorthand boolean attributes in Prisma PHP markup. Write them explicitly.
-
-Correct:
-
-```xml
-<input disabled="true" />
-<option selected="true">Admin</option>
-```
-
-Incorrect:
-
-```xml
-<input disabled />
-<option selected>Admin</option>
-```
-
-### AI rule
-
-When generating Prisma PHP markup, always treat it as **strict XML**, not permissive HTML and not JSX shorthand.
-
-## How to use the docs
-
-The docs are organized into multiple sections so you can learn Prisma PHP progressively:
-
-- [Get Started](/docs): Learn the fundamentals, project structure, commands, tools, environment setup, routing, file conventions, HTML attributes, JavaScript usage, class usage, and authentication.
-- [Starter Kits](/docs): Learn how installation works, how starter kits are structured, and how to create your own.
-- [PHPX](/docs): Learn the component model and how to build reusable UI with PHP-first syntax.
-- [ORM](/docs): Learn Prisma config, database setup, CLI usage, seeding, relations, reading, writing, filtering, aggregates, raw queries, transactions, and field selection.
-- [API](/docs): Learn the API features and Swagger docs support.
-- [AI](/docs): Learn the AI-related features, MCP support, and framework rules.
-- [Additional Features](/docs): Explore file manager, pagination, debug tooling, websocket support, and email.
-- [PulsePoint Runtime Rules](./pulsepoint): Learn the approved PulsePoint runtime surface, directives, refs, effects, and frontend reactive patterns AI should follow.
-
-Use the sidebar to navigate through sections, or search with the command palette (`Ctrl+K`) to quickly find a page.
-
-## Core framework areas
-
-Prisma PHP brings together a few major parts of the stack:
-
-- **Native PHP application model**: Build with PHP-first conventions instead of shifting your app architecture around JavaScript tooling.
-- **PulsePoint reactivity**: Use browser-resident state and reactive UI patterns directly in your pages.
-- **Prisma ORM**: Query your database with a type-safe developer experience.
-- **PHPX UI approach**: Build reusable components with HTML-like syntax and server-rendered ergonomics.
-- **Routing and file conventions**: Follow Next.js-style routing concepts adapted for Prisma PHP.
-
-This combination lets you keep your backend and frontend closer together, with less transformation and less glue code between server data and interactive UI.
-
-## Routing and application structure
-
-Prisma PHP includes a documented routing system with dedicated pages for:
-
-- Routing Fundamentals
-- Defining Routes
-- Pages and Layouts
-- Redirects
-- Route Groups
-- Private Folders
-- Dynamic Routes
-- Middleware
-
-It also defines file conventions such as:
+Important files include:
 
 - `index.php`
 - `layout.php`
@@ -183,61 +124,19 @@ Routes are created from the `src/app` folder structure and route files. AI agent
 
 If you are changing route behavior or navigation patterns, read the routing documentation first.
 
-## Data, ORM, and reactivity
+## Data and reactivity
 
 One of Prisma PHP’s core ideas is keeping data flow simple across the stack:
 
-- query data with Prisma ORM in PHP
-- render full-stack UI directly from route files
-- use PulsePoint for frontend reactivity
-- use `pp.fetchFunction(...)` for reactive frontend-to-server calls
-- expose callable PHP functions with `#[Exposed]`
+- Query data with Prisma ORM in PHP
+- Render full-stack UI directly from route files
+- Use PulsePoint for frontend reactivity
+- Use `pp.fetchFunction(...)` for reactive frontend-to-server calls
+- Expose callable PHP functions with `#[Exposed]`
+- Validate incoming request data with `PP\Validator`
 
 This makes it easier to build interactive applications without maintaining separate DTO layers, excessive transformation code, or client-heavy hydration logic.
 
-When a task specifically involves PulsePoint runtime behavior such as `pp.state`, `pp.effect`, `pp.ref`, `pp-for`, `pp-spread`, or `pp-ref`, read `pulsepoint.md` before generating code.
-
-When a task involves Prisma ORM setup or schema changes, read `prisma-php-orm.md` first. That document should be the source of truth for:
-
-- confirming whether the project is using SQLite, MySQL, PostgreSQL, or another configured provider
-- reading `.env` and validating `DATABASE_URL` before making ORM setup assumptions
-- resolving the correct database setup path for the configured provider
-- understanding when to run `npx prisma migrate dev`
-- understanding when to run `npx ppo generate`
-- avoiding the mistake of treating generated PHP classes as proof that the database is already initialized
-- avoiding the mistake of treating project update commands as ORM sync commands
-
-When a task involves frontend interaction that needs server data or mutations, prefer the documented Prisma PHP pattern of PulsePoint reactive state plus `pp.fetchFunction(...)` before inventing custom endpoint flows.
-
-## Pre-requisite knowledge
-
-Our documentation assumes some familiarity with web development. Before getting started, it helps if you are comfortable with:
-
-- PHP
-- HTML
-- CSS
-- JavaScript
-- Databases and basic ORM concepts
-
-Familiarity with reactive UI concepts is also useful when working with PulsePoint-powered interfaces.
-
-## Documentation philosophy
-
-Prisma PHP evolves quickly, and framework behavior may differ across versions.
-
-If you are an AI coding agent or working with generated code:
-
-- do not rely on assumptions from other PHP frameworks
-- do not assume Laravel, Symfony, or Next.js behavior maps directly
-- do not guess file conventions, routing behavior, or Prisma workflow
-- always read the relevant local documentation for the installed version before making changes
-- always read `pulsepoint.md` before generating PulsePoint-specific reactive UI code
-- always read `prisma-php-orm.md` before making database-provider, `.env`, migration, or ORM generation decisions
-- always follow Prisma PHP XML-style syntax rules when generating PHPX or template markup
-- never manually maintain framework-generated route listing files such as `files-list.json`
-
-The installed documentation should be treated as the source of truth.
-
-## Join the community
+When Prisma ORM data is loaded in `index.php`, treat normal query results as the model-shaped objects returned by the generated Prisma PHP classes that follow `prisma/schema.prisma`.
 
-If you want to explore Prisma PHP further, start with the official documentation, check the GitHub repository, and follow the broader ecosystem around PulsePoint, PHPX UI, and related tooling.
+Do not introduce defensive serializer layers by default just to make normal ORM results usable. Use `PP\Validator` for incoming payload validation, sanitization, casting, and rule-based checks. Only add a presentation mapper when you intentionally need a client-facing shape, such as flattening included relations, hiding sensitive fields, or formatting values for display.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prisma-php",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Prisma PHP tooling",
   "main": "index.js",
   "scripts": {

package/dist/docs/01-getting-started/index.md

@@ -1,142 +0,0 @@
----
-title: Prisma PHP Docs
-description: Welcome to the Prisma PHP Documentation.
-related:
-  title: Next Steps
-  description: Create your first Prisma PHP application and learn the core framework features.
-  links:
-    - /docs/get-started
----
-
-{/_ AI agent hint: Prisma PHP uses local installed docs as the source of truth for the active project version. Before generating framework-specific code, read `prisma-php.json` first, then read the relevant docs from `node_modules/prisma-php/dist/docs`. For authentication, read `authentication.md` first, then verify the official auth docs: `auth-get-started`, `credentials`, and `state-manager-auth`. For file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, or file manager screens, read `file-manager.md` first, then verify the official File Manager docs: `get-started-file`. For ORM work, read `prisma-php-orm.md` before choosing schema, migration, or generation commands. For PulsePoint runtime behavior specifically, read `pulsepoint.md` before generating reactive UI code. For backend validation, sanitization, `Validator`, `Rule`, `pp.fetchFunction(...)` validation flows, or request validation in `route.php`, read `fetching-data.md`, `error-handling.md`, and `route-handlers.md`, then consult the official Validator docs. `PP\Validator` is a Prisma PHP core class located in `vendor/tsnc/prisma-php/src/Validator.php`. Route creation is file-based from `src/app`; Prisma PHP auto-generates route listings such as `files-list.json`, so AI agents must not create, edit, or maintain that file manually. _/}
-
-Welcome to the Prisma PHP documentation!
-
-## What is Prisma PHP?
-
-Prisma PHP is a full-stack PHP framework for building modern, reactive web applications.
-
-You use native PHP to build your application, Prisma ORM for type-safe data access, and PulsePoint to add reactive browser state without the usual API glue or hydration-heavy workflow.
-
-It is designed to give you a server-first development model with modern UI interactivity, reusable PHPX components, Next.js-style routing concepts adapted for Prisma PHP, and CLI tooling.
-
-Whether you're building an internal dashboard, a content-rich platform, or a custom product, Prisma PHP helps you move fast while keeping your stack cohesive and expressive.
-
-## AI quick start
-
-If you are using AI-assisted development, do not guess framework behavior from other ecosystems.
-
-Use this order:
-
-1. Read `./prisma-php.json` first.
-2. Read the relevant local docs in `node_modules/prisma-php/dist/docs`.
-3. Inspect local project files.
-4. Inspect `vendor/tsnc/prisma-php/src` only when framework internals are necessary.
-
-### Read this doc when you need
-
-- **project setup or file placement** → `project-structure.md`
-- **pages, layouts, route creation, nested routes** → `layouts-and-pages.md`
-- **PHPX components, props, children, fragments, icons, buttons, accordions, or component composition** → `components.md`
-- **file uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename/delete flows, file replacement, allowed file types, upload size rules, or file manager pages** → `file-manager.md`
-- **authentication strategy, `AuthConfig.php`, sign-in, sign-out, route privacy model, RBAC, credentials auth, social login, or auth state manager usage** → `authentication.md`
-- **`pp.fetchFunction(...)`, `#[Exposed]`, page data loading, interactive validation with `Validator`** → `fetching-data.md`
-- **cache behavior and `CacheHandler`** → `caching.md`
-- **ORM, `schema.prisma`, database provider, migrations, generated PHP classes, `prisma.config.ts`, `.env` `DATABASE_URL`, or Prisma CLI workflow** → `prisma-php-orm.md`
-- **error handling, `error.php`, `not-found.php`, expected validation errors** → `error-handling.md`
-- **metadata, title, description, favicon, icons** → `metadata-and-og-images.md`
-- **API-style endpoints, `route.php`, request validation with `Validator`** → `route-handlers.md`
-- **PulsePoint runtime APIs such as `pp.state`, `pp.effect`, `pp.ref`, `pp-for`, `pp-ref`, `pp-spread`** → `pulsepoint.md`
-- **updating the project or enabling features** → `upgrading.md`
-- **first-time project creation** → `installation.md`
-
-### Important AI rules
-
-- treat `node_modules/prisma-php/dist/docs` as the primary documentation source for the installed version
-- do not assume Laravel, Symfony, React, Vue, Alpine, Livewire, or Next.js behavior maps directly
-- do not guess routing, file conventions, request helpers, component APIs, reactive syntax, or auth behavior when local docs already define them
-- create routes by adding folders and route files under `src/app`
-- do not create, edit, or maintain `files-list.json`; Prisma PHP generates route listings automatically
-- when building interactive frontend behavior, prefer the documented PulsePoint pattern with browser-side reactive state and `pp.fetchFunction(...)` for server calls
-- when using `pp.fetchFunction(...)`, expose the PHP function explicitly with `#[Exposed]`
-- when changing feature flags, update `prisma-php.json` first, then follow the documented update workflow
-- when building reusable PHPX components, read `components.md` first
-- when building file-upload flows, file listings, rename/delete actions, or a file manager screen, read `file-manager.md` first and keep the implementation aligned with Prisma PHP’s documented File Manager model
-- when building auth flows, protection rules, or login/register pages, read `authentication.md` first and keep the implementation aligned with Prisma PHP’s documented auth model
-
-## File Manager
-
-Prisma PHP includes a documented File Manager model for uploads and file operations based on standard PHP uploads plus `PP\FileManager\UploadFile`.
-
-Use `file-manager.md` as the local AI-awareness guide for:
-
-- upload forms with `multipart/form-data`
-- `$_FILES` handling
-- `PP\FileManager\UploadFile`
-- upload size and type restrictions
-- rename, replace, and delete flows
-- choosing between a rendered upload page and a direct upload handler
-- validating non-file request values with `PP\Validator`
-
-After reading `file-manager.md`, verify the matching official docs at:
-
-1. `get-started-file`
-2. `php-validator` when auxiliary request validation is needed
-3. `route-php` or `pages-and-layouts` depending on whether the task is a direct handler or a full-stack page
-
-## Authentication
-
-Prisma PHP includes a documented authentication model centered on sessions, route protection strategy, RBAC, and provider-based sign-in flows.
-
-Use `authentication.md` as the local AI-awareness guide for:
-
-- `AuthConfig.php`
-- public-default vs private-default route strategy
-- `Auth::signIn(...)`
-- `Auth::signOut(...)`
-- `refreshUserSession(...)`
-- route-level RBAC
-- function-level protection with `#[Exposed(allowedRoles: [...])]`
-- credential authentication
-- social authentication
-
-After reading `authentication.md`, verify the matching official docs in this order:
-
-1. `auth-get-started`
-2. `credentials`
-3. `state-manager-auth`
-
-## Routing and file conventions
-
-Prisma PHP uses file-based routing.
-
-Important files include:
-
-- `index.php`
-- `layout.php`
-- `loading.php`
-- `route.php`
-- `not-found.php`
-- `error.php`
-- metadata files and icons
-
-Routes are created from the `src/app` folder structure and route files. AI agents should not try to register routes manually in framework-generated route list files.
-
-If you are changing route behavior or navigation patterns, read the routing documentation first.
-
-## Data and reactivity
-
-One of Prisma PHP’s core ideas is keeping data flow simple across the stack:
-
-- Query data with Prisma ORM in PHP
-- Render full-stack UI directly from route files
-- Use PulsePoint for frontend reactivity
-- Use `pp.fetchFunction(...)` for reactive frontend-to-server calls
-- Expose callable PHP functions with `#[Exposed]`
-- Validate incoming request data with `PP\Validator`
-
-This makes it easier to build interactive applications without maintaining separate DTO layers, excessive transformation code, or client-heavy hydration logic.
-
-When Prisma ORM data is loaded in `index.php`, treat normal query results as the model-shaped objects returned by the generated Prisma PHP classes that follow `prisma/schema.prisma`.
-
-Do not introduce defensive serializer layers by default just to make normal ORM results usable. Use `PP\Validator` for incoming payload validation, sanitization, casting, and rule-based checks. Only add a presentation mapper when you intentionally need a client-facing shape, such as flattening included relations, hiding sensitive fields, or formatting values for display.