create-prisma-php-app 5.0.0-alpha.17 → 5.0.0-alpha.19

package/dist/AGENTS.md

@@ -2,66 +2,51 @@
 
 # Prisma PHP AI Agent Rules
 
-This repository is the Prisma PHP package and docs workspace, not a generated Prisma PHP application.
+This AGENTS.md belongs in the root of a Prisma PHP application.
 
-Treat `dist/docs/index.md` as the entry point for Prisma PHP guidance in this repo, then read the matching document in `dist/docs` before generating, editing, reviewing, or documenting framework-specific behavior.
+Treat `./node_modules/prisma-php/dist/docs/index.md` as the entry point for Prisma PHP guidance, then read the matching document in `./node_modules/prisma-php/dist/docs` before generating, editing, reviewing, or documenting framework-specific behavior.
 
-Do not guess framework behavior from Laravel, Next.js, React, Vue, Livewire, Alpine, Symfony, Socket.IO, or generic PHP habits. Prisma PHP's local docs and the current repository context are the source of truth.
+Do not guess framework behavior from Laravel, Next.js, React, Vue, Livewire, Alpine, Symfony, Socket.IO, or generic PHP habits. Prisma PHP's installed docs in `./node_modules/prisma-php/dist/docs` and the current project files are the source of truth.
 
-## Repository mode vs app mode
+## Documentation source of truth
 
-There are two valid Prisma PHP contexts, and AI must not mix them up.
-
-### 1. Package/docs repo mode
-
-This workspace is package/docs repo mode.
-
-In this repo, use this order first:
+For Prisma PHP projects, use this order first:
 
 1. the user's explicit request
-2. `dist/docs/index.md`
-3. the relevant document in `dist/docs`
-4. `.github/copilot-instructions.md`
-5. `package.json` and nearby repo files
-6. Prisma PHP core internals only when the docs still leave a gap
+2. `./prisma-php.json`
+3. the relevant installed document in `./node_modules/prisma-php/dist/docs`
+4. `./AGENTS.md`
+5. project-local conventions and existing app files
+6. Prisma PHP core internals in `vendor/tsnc/prisma-php/src` only when the docs still leave a gap
 7. general framework knowledge as the last fallback
 
-Important repo-mode rules:
-
-- do not assume `./prisma-php.json` exists in this repository
-- do not assume `node_modules/prisma-php/dist/docs` is the active docs location for this workspace
-- do not assume `vendor/tsnc/prisma-php/src` exists locally in this workspace unless the task explicitly provides or references it
-- when editing or improving Prisma PHP guidance in this repo, keep `AGENTS.md`, `.github/copilot-instructions.md`, and `dist/docs` aligned with each other
-
-### 2. Consumer app mode
+Important rules:
 
-When a task is about a generated Prisma PHP application rather than this package repo, use this app-mode order:
+- treat `./node_modules/prisma-php/dist/docs` as the single documentation source of truth for the installed Prisma PHP version
+- expect `./AGENTS.md` at the project root
+- when the installed docs and a habit from another framework conflict, follow Prisma PHP
+- when updating Prisma PHP package/docs sources, keep `AGENTS.md`, `.github/copilot-instructions.md`, and `dist/docs` aligned so the published docs stay correct after install
 
-1. the user's explicit request
-2. `./prisma-php.json`
-3. installed Prisma PHP docs in `node_modules/prisma-php/dist/docs`
-4. project-local conventions and existing app files
-5. Prisma PHP core internals in `vendor/tsnc/prisma-php/src`
-6. general framework knowledge
+## Installed docs location
 
-If a documented Prisma PHP rule conflicts with a habit from another framework, follow Prisma PHP.
+In Prisma PHP applications, the installed docs live in:
 
-## Source of truth in this repo
+```txt
+node_modules/prisma-php/dist/docs
+```
 
-The Prisma PHP docs shipped in this repository live in:
+The current docs entry point for the installed version is:
 
 ```txt
-dist/docs
+node_modules/prisma-php/dist/docs/index.md
 ```
 
-The current docs entry point in this repository is:
+The project root should also include:
 
 ```txt
-dist/docs/index.md
+AGENTS.md
 ```
 
-When updating AI guidance for Prisma PHP itself, treat `dist/docs` as the authoritative local documentation surface for this workspace.
-
 ## Required doc-routing map
 
 Before generating code, examples, instructions, or reviews, choose the documentation file based on the task.
@@ -74,21 +59,36 @@ Before generating code, examples, instructions, or reviews, choose the documenta
 - **Project setup, folder placement, route file choice, feature placement, or overall file conventions**  
   Read `project-structure.md`
 
+- **CLI project creation, starter kits, feature flags, or `npx pp update project` usage**  
+  Read `commands.md`
+
+- **Backend-only Prisma PHP usage, API-first projects, `backendOnly`, separate frontend consumers, or CORS setup for API routes**  
+  Read `backend-only.md`
+
 - **Creating a page, layout, nested route, dynamic route, or normal UI route**  
   Read `layouts-and-pages.md`
 
 - **Creating, editing, composing, or reviewing PHPX components, props, children, fragments, icons, buttons, accordions, or component file placement**  
   Read `components.md`
 
+- **TypeScript frontend tooling, the `typescript` feature flag, the root `ts/` directory, `ts/main.ts`, npm packages, or registered browser helpers used from template expressions and PulsePoint scripts**  
+  Read `typescript.md`, then use `pulsepoint.md`, `layouts-and-pages.md`, or `components.md` for the affected component boundary
+
 - **Loading data, calling backend logic from the frontend, `pp.fetchFunction(...)`, `#[Exposed]`, route-local mutations, streaming responses, or interactive backend validation**  
   Read `fetching-data.md`
 
+- **AI integration, provider SDKs, chat UIs, streamed assistant output, or deciding between page-local assistant UI, websocket, and MCP tools**  
+  Read `get-started-ia.md`, then use `fetching-data.md`, `validator.md`, `websocket.md`, or `mcp.md` as needed
+
 - **PulsePoint runtime behavior such as `pp.state`, `pp.effect`, `pp-for`, `pp-spread`, or `pp-ref`**  
   Read `pulsepoint.md`
 
 - **Validation, sanitization, `PP\Validator`, `PP\Rule`, field validation, form validation, live validation, or request validation rules**  
   Read `validator.md`, then apply the relevant local guidance from `fetching-data.md`, `error-handling.md`, and `route-handlers.md`
 
+- **Environment variables, `.env`, `PP\Env`, `Env::get`, `Env::string`, `Env::bool`, `Env::int`, feature flags, host and port config, or runtime bootstrap settings**  
+  Read `env.md`, then verify the official env docs at `env` and `env-file`
+
 - **File uploads, `multipart/form-data`, `$_FILES`, `PP\FileManager\UploadFile`, rename flows, replace flows, delete flows, allowed file types, upload size rules, or file manager UI behavior**  
   Read `file-manager.md`, then verify the official File Manager docs and, when internals matter, the core upload file at `vendor/tsnc/prisma-php/src/FileManager/UploadFile.php`
 
@@ -119,6 +119,9 @@ Before generating code, examples, instructions, or reviews, choose the documenta
 - **API-style routes, JSON responses, handlers, webhooks, form-processing endpoints, `route.php`, or request validation in handlers**  
   Read `route-handlers.md`
 
+- **Swagger or OpenAPI generation, `swaggerDocs`, `pphp-swagger.json`, `create-swagger-docs`, or `settings/prisma-schema-config.json`**  
+  Read `swagger-docs.md`
+
 - **Upgrading Prisma PHP, enabling features, syncing framework-managed project files, or running project updates**  
   Read `upgrading.md`
 
@@ -130,12 +133,16 @@ Before generating code, examples, instructions, or reviews, choose the documenta
 The current Prisma PHP docs shipped here include:
 
 - `authentication.md`
+- `backend-only.md`
 - `caching.md`
+- `commands.md`
 - `components.md`
 - `email.md`
+- `env.md`
 - `error-handling.md`
 - `fetching-data.md`
 - `file-manager.md`
+- `get-started-ia.md`
 - `index.md`
 - `installation.md`
 - `layouts-and-pages.md`
@@ -145,11 +152,13 @@ The current Prisma PHP docs shipped here include:
 - `project-structure.md`
 - `pulsepoint.md`
 - `route-handlers.md`
+- `swagger-docs.md`
+- `typescript.md`
 - `upgrading.md`
 - `validator.md`
 - `websocket.md`
 
-When adding or reviewing AI guidance, do not stop at older docs only. Make sure the guidance also covers `email.md`, `mcp.md`, and `websocket.md`, plus newer behavior documented in `fetching-data.md` and `metadata-and-og-images.md`.
+When adding or reviewing AI guidance, do not stop at older docs only. Make sure the guidance also covers `backend-only.md`, `email.md`, `env.md`, `get-started-ia.md`, `mcp.md`, `swagger-docs.md`, `typescript.md`, and `websocket.md`, plus newer behavior documented in `fetching-data.md` and `metadata-and-og-images.md`.
 
 ## Framework-generated files
 
@@ -249,7 +258,6 @@ Use this pattern:
 1. PHP first
 2. exactly one parent root element
 3. keep any component-local `<script>` inside that root element
-4. let Prisma PHP inject `pp-component` for that boundary automatically
 
 Example:
 
@@ -260,7 +268,7 @@ Example:
 
 ?>
 
-<div>
+<div pp-component="search-box">
     <h2>Search</h2>
     <input value="{query}" />
     <script>
@@ -340,20 +348,11 @@ In a consumer app, also verify `backendOnly` in `prisma-php.json`:
 
 Use this workflow unless the user asks for something narrower.
 
-### For this repository
-
-1. read `dist/docs/index.md`
-2. read the relevant document in `dist/docs`
-3. inspect nearby docs, examples, and guidance files in this repo
-4. keep `AGENTS.md` and `.github/copilot-instructions.md` aligned with the documented behavior
-5. inspect framework internals only when the docs still leave a real gap
-
-### For consumer app examples or generated-app tasks
-
 1. read `./prisma-php.json`
-2. read the relevant installed doc from `node_modules/prisma-php/dist/docs`
-3. inspect nearby project files that match the route, feature, or component being changed
-4. inspect `vendor/tsnc/prisma-php/src` only if the docs do not answer the task
+2. read the relevant installed doc from `./node_modules/prisma-php/dist/docs`
+3. inspect `./AGENTS.md` for project-level Prisma PHP guidance
+4. inspect nearby project files that match the route, feature, or component being changed
+5. inspect `vendor/tsnc/prisma-php/src` only if the docs do not answer the task
 
 Do not jump directly into framework internals if the current docs already answer the task.
 
@@ -432,6 +431,26 @@ Important email rules:
 - prefer the documented fluent API such as `to(...)`, `subject(...)`, `html(...)`, `text(...)`, `attach(...)`, and `send()`
 - use `raw()` only when low-level PHPMailer access is genuinely needed
 
+## Env rules
+
+When the task involves `.env`, `PP\Env`, feature flags, ports, host names, timezones, API keys, numeric limits, or other runtime configuration values, read `env.md` first.
+
+Use this env workflow:
+
+1. read `env.md`
+2. inspect `.env` or the deployment environment when the task depends on actual values
+3. inspect the bootstrap or server entry file that loads or consumes the environment
+4. inspect the feature-specific doc such as `email.md`, `mcp.md`, `websocket.md`, `get-started-ia.md`, or `prisma-php-orm.md` when the env values belong to that feature
+5. inspect `vendor/tsnc/prisma-php/src/Env.php` only if the docs do not answer the task
+
+Important env rules:
+
+- prefer `PP\Env` over repeated ad hoc `getenv()` parsing in documented Prisma PHP code paths
+- use `Env::string(...)`, `Env::bool(...)`, and `Env::int(...)` for typed access with defaults
+- use `Env::get(...)` when raw nullable string access is actually needed
+- remember that `PP\Env` reads values from `getenv()`, `$_ENV`, and `$_SERVER`; it does not parse `.env` by itself
+- keep secrets and deployment-specific settings in `.env` or the real runtime environment, not hardcoded in route files or components
+
 ## WebSocket rules
 
 When the task involves realtime messaging, presence, live dashboards, `Ratchet`, or browser `WebSocket`, read `websocket.md` first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-prisma-php-app",
-  "version": "5.0.0-alpha.17",
+  "version": "5.0.0-alpha.19",
   "description": "Prisma-PHP: A Revolutionary Library Bridging PHP with Prisma ORM",
   "main": "dist/index.js",
   "type": "module",

package/dist/README.md

@@ -1,213 +0,0 @@
-# Prisma PHP
-
-Prisma PHP is a modern full-stack PHP framework that combines native PHP, PulsePoint reactivity, PHPX components, and a Prisma-inspired ORM into one cohesive developer experience.
-
-Build reactive interfaces with a server-first mental model, structured routing, type-safe data access, and a project layout designed for real applications.
-
-## Getting Started
-
-Create a new Prisma PHP project:
-
-```bash
-npx create-prisma-php-app@latest my-app
-```
-
-Start the development server:
-
-```bash
-npm run dev
-```
-
-Open the local app in your browser after the dev server starts.
-
-## Prerequisites
-
-Before creating a Prisma PHP project, make sure you have:
-
-- Node.js 22.x or higher
-- PHP 8.2 or higher
-- Composer 2.x or higher
-- XAMPP or another local PHP environment
-
-If you are using XAMPP on Windows, enabling `extension=zip` in `php.ini` is recommended so Composer dependencies install correctly.
-
-## What Prisma PHP Includes
-
-Prisma PHP brings together the core pieces needed to build full-stack PHP apps:
-
-- **Native PHP + modern reactivity** with PulsePoint
-- **PHPX component system** for reusable UI composition
-- **Prisma PHP ORM** for schema-first, type-safe database access
-- **Built-in authentication patterns** for sessions, route protection, RBAC, credentials auth, and provider login
-- **File-based routing** with clear route file conventions
-- **CLI scaffolding** for new apps, starter kits, and optional features
-- **Flexible deployment options** for local development and production workflows
-
-## Common Create Commands
-
-Create a default full-stack app:
-
-```bash
-npx create-prisma-php-app@latest my-app
-```
-
-Create a project with common options:
-
-```bash
-npx create-prisma-php-app@latest my-app --tailwindcss --typescript
-```
-
-Use a starter kit:
-
-```bash
-npx create-prisma-php-app my-app --starter-kit=fullstack
-```
-
-Other documented flags may include capabilities such as WebSocket support, MCP support, backend-only mode, Swagger docs, and Prisma integration depending on the installed version.
-
-## Documentation
-
-Prisma PHP ships with local documentation for the installed project version.
-
-The installed docs live here:
-
-```txt
-node_modules/prisma-php/dist/docs
-```
-
-Treat these installed docs as the primary documentation source for the current project version.
-
-You can also explore the public docs site:
-
-```txt
-https://prismaphp.tsnc.tech/
-```
-
-## AI Quick Start
-
-If you are using AI-assisted development in a Prisma PHP project:
-
-1. Read `./prisma-php.json` first.
-2. Read the installed docs in `node_modules/prisma-php/dist/docs`.
-3. Read `AGENTS.md` for task-routing rules, framework constraints, and code-generation guidance.
-4. Inspect `vendor/tsnc/prisma-php/src` only when the docs do not answer the task.
-
-### Default interactive UI rule
-
-In Prisma PHP, AI should treat **PulsePoint as the default frontend interactivity model**.
-
-For normal full-stack page work:
-
-- render the page with `index.php`
-- manage browser-side state and UI behavior with **PulsePoint**
-- call PHP from the frontend with **`pp.fetchFunction(...)`**
-- expose callable PHP functions with **`#[Exposed]`**
-- validate incoming data on the PHP side with **`PP\Validator`**
-
-Do **not** default to PHP-only refresh cycles, handcrafted `fetch('/api/...')` patterns, or extra `route.php` handlers for normal interactive page behavior when PulsePoint plus `pp.fetchFunction(...)` already fits the task.
-
-Only prefer a more PHP-only interaction style when the **user explicitly asks for PHP-only behavior**, or when the task is clearly non-reactive.
-
-## Project Capability Manifest
-
-Prisma PHP uses `prisma-php.json` at the repository root as the source of truth for enabled framework features and local environment configuration.
-
-Use it to verify capabilities such as:
-
-- Tailwind CSS support
-- backend-only mode
-- Prisma ORM support
-- Swagger docs
-- WebSocket support
-- MCP support
-- TypeScript support
-- local development paths and BrowserSync settings
-
-Do not assume a feature is enabled unless `prisma-php.json` confirms it.
-
-## Documentation Map
-
-Use these docs as the main entry points for common work:
-
-- `index.md` for the general documentation entry point
-- `project-structure.md` for project structure, route placement, and file conventions
-- `layouts-and-pages.md` for pages, layouts, nested routes, and dynamic routes
-- `components.md` for PHPX components, props, children, fragments, icons, buttons, and composition
-- `fetching-data.md` for `pp.fetchFunction(...)`, `#[Exposed]`, and interactive backend flows
-- `prisma-php-orm.md` for Prisma ORM, `schema.prisma`, migrations, and generated PHP classes
-- `authentication.md` for auth strategy, sessions, RBAC, credentials auth, and provider flows
-- `file-manager.md` for uploads, `multipart/form-data`, `$_FILES`, and `PP\FileManager\UploadFile`
-- `route-handlers.md` for `route.php`, JSON responses, and direct server handlers
-- `error-handling.md` for expected errors, `error.php`, `not-found.php`, and validation failures
-- `caching.md` for cache behavior and `CacheHandler`
-- `metadata-and-og-images.md` for metadata, title, description, icons, and head behavior
-- `pulsepoint.md` for PulsePoint runtime usage and reactivity patterns
-- `upgrading.md` for feature enablement and project update workflows
-
-## Recommended Development Approach
-
-When working in Prisma PHP:
-
-- prefer the installed Prisma PHP docs over assumptions from other frameworks
-- use `AGENTS.md` as the strict AI operating guide
-- inspect nearby project files before generating new framework-specific code
-- inspect framework internals only when the installed docs are not enough
-
-## Route and File Conventions
-
-Prisma PHP uses file-based routing with special route files such as:
-
-- `index.php` for rendered UI routes
-- `layout.php` for shared UI wrappers
-- `route.php` for direct handlers such as JSON or API-style endpoints
-- `loading.php` for loading UI
-- `not-found.php` for route-level not-found UI
-- `error.php` for route-level or app-level error UI
-
-For task-specific route decision rules and framework generation rules, read `AGENTS.md`.
-
-## PulsePoint and Frontend Reactivity
-
-Prisma PHP uses PulsePoint for browser-side reactivity, and AI should assume this is the **default choice** for interactive UI behavior in full-stack routes.
-
-When working with runtime features such as:
-
-- `pp.state`
-- `pp.effect`
-- `pp.ref`
-- `pp-for`
-- `pp-spread`
-- `pp-ref`
-
-read the installed Prisma PHP docs for the current version first, then consult:
-
-```txt
-https://pulsepoint.tsnc.tech/llms
-```
-
-## Project Structure
-
-A generated Prisma PHP project typically includes folders like these:
-
-```text
-prisma-php-project/
-├── prisma/            # schema, migrations, seed files
-├── public/            # public entry point and assets
-├── settings/          # project configuration
-├── src/               # application source code
-├── package.json       # frontend/dev scripts
-├── composer.json      # PHP dependencies
-└── prisma-php.json    # Prisma PHP project capability manifest
-```
-
-## Updating Existing Projects
-
-When enabling features or syncing framework-managed project files:
-
-1. Update `prisma-php.json` first.
-2. Read `upgrading.md` in the installed docs.
-3. Run the documented project update workflow for the current version.
-
-## Learn More
-
-Start with the installed docs for the current project version, use the topic-specific markdown guides for focused work, and rely on `AGENTS.md` when strict AI generation rules are needed.