@abeedoo/radish-schemas 1.7.7

package/prompts/radish-ui-generation.md

@@ -0,0 +1,227 @@
+# AI UI Blueprint Generation Prompt
+
+You are an expert UI architect. Generate a JSON UI blueprint that defines routes, pages, layouts, and content blocks for a web application.
+
+**Generate ONLY the UI blueprint. Do NOT include types, roles, or app metadata.**
+
+The UI blueprint references entities defined in the types blueprint. Content blocks are entity-driven — the generator reads entity metadata (fields, types, relationships) to auto-generate tables, forms, and detail views.
+
+## Blueprint Structure
+
+```json
+{
+  "version": 1,
+  "app": {
+    "name": "AppName",
+    "description": "Short description for display"
+  },
+  "routes": [
+    {
+      "path": "/",
+      "page": "home",
+      "title": "Home",
+      "access": "public"
+    }
+  ],
+  "pages": {
+    "home": {
+      "layout": {
+        "header": true,
+        "navigation": true,
+        "footer": true
+      },
+      "content": [
+        { "type": "hero", "title": "Welcome to {app.name}", "subtitle": "{app.description}" }
+      ]
+    }
+  }
+}
+```
+
+## Routes
+
+Each route maps a URL path to a page definition.
+
+**Properties:**
+- `path` (required): URL pattern. Use `[param]` for dynamic segments
+- `page` (required): Page identifier (lowercase-hyphenated, must match a key in `pages`)
+- `title` (optional): Page title for navigation and breadcrumbs
+- `access` (required): One of:
+  - `"public"` — anyone can access
+  - `"authenticated"` — logged-in users only
+  - `{ "roles": ["ADMIN"], "permissions": ["entity:action"] }` — role/permission-based
+
+**Route path patterns:**
+```json
+{ "path": "/", "page": "home", "access": "public" }
+{ "path": "/courses", "page": "courses-list", "access": "authenticated" }
+{ "path": "/courses/[id]", "page": "course-detail", "access": "authenticated" }
+{ "path": "/courses/create", "page": "course-create", "access": { "roles": ["ADMIN", "INSTRUCTOR"] } }
+{ "path": "/courses/[courseId]/modules", "page": "modules-list", "access": "authenticated" }
+```
+
+## Pages
+
+Each page has an optional layout and an array of content blocks.
+
+**Layout properties (all boolean, all optional):**
+- `header` — show application header
+- `navigation` — show main navigation
+- `sidebar` — show sidebar
+- `footer` — show application footer
+
+## Content Block Types
+
+### 1. `hero`
+Landing section with title and subtitle.
+
+```json
+{
+  "type": "hero",
+  "title": "Welcome to {app.name}",
+  "subtitle": "{app.description}"
+}
+```
+
+Supports interpolation: `{app.name}`, `{app.description}`
+
+### 2. `entity-list`
+Display a list/table/grid of entities. Fields auto-detected from entity metadata if not specified.
+
+```json
+{
+  "type": "entity-list",
+  "entity": "Course",
+  "display": "table",
+  "title": "All Courses",
+  "limit": 20,
+  "fields": ["title", "status", "createdAt"],
+  "filter": {
+    "field": "instructorId",
+    "value": "{user.id}"
+  },
+  "sort": {
+    "field": "createdAt",
+    "direction": "desc"
+  }
+}
+```
+
+- `entity` (required): PascalCase entity name from types blueprint
+- `display`: `"table"`, `"grid"`, or `"list"` (default: `"table"`)
+- `title`: Section heading
+- `limit`: Max items to display
+- `fields`: Array of field names to show (omit to auto-detect from entity)
+- `filter`: Filter by field/value with interpolation support
+- `sort`: Default sort field and direction (`"asc"` or `"desc"`)
+
+### 3. `entity-detail`
+Display a single entity with its fields.
+
+```json
+{
+  "type": "entity-detail",
+  "entity": "Course",
+  "title": "Course Details",
+  "fields": ["title", "description", "price", "status"],
+  "actions": ["edit", "delete"]
+}
+```
+
+- `entity` (required): PascalCase entity name
+- `title`: Section heading
+- `fields`: Array of field names to show (omit to auto-detect)
+- `actions`: Action buttons — `"edit"` and/or `"delete"`
+
+### 4. `entity-form`
+Create or edit form for an entity. Fields and validation auto-detected from entity metadata.
+
+```json
+{
+  "type": "entity-form",
+  "entity": "Course",
+  "action": "create",
+  "title": "Create Course",
+  "fields": ["title", "description", "price", "category"]
+}
+```
+
+- `entity` (required): PascalCase entity name
+- `action`: `"create"` or `"edit"` (default: `"create"`)
+- `title`: Form heading
+- `fields`: Array of field names to include (omit to auto-detect)
+
+## Interpolation
+
+Content blocks support interpolation for dynamic values:
+
+- `{app.name}` — Application name
+- `{app.description}` — Application description
+- `{entity.id}` — Current entity ID from route param (e.g., `{course.id}`)
+- `{paramName}` — Route parameter (e.g., `{courseId}` from `/courses/[courseId]/modules`)
+- `{user.id}` — Current logged-in user ID
+
+## Design Guidelines
+
+### Route Design
+- Start with `/` as the landing page (usually `"public"`)
+- Use CRUD patterns: `/entities` (list), `/entities/[id]` (detail), `/entities/create` (form)
+- Nest related entities: `/courses/[courseId]/modules`
+- Put admin routes behind role-based access
+- Every route must have a matching page key
+
+### Page Design
+- Most pages should have `header: true`, `navigation: true`, `footer: true`
+- Home page should have a hero block + featured entity list
+- List pages: one `entity-list` block, typically `"table"` display
+- Detail pages: one `entity-detail` block, optionally followed by related `entity-list` blocks
+- Create/edit pages: one `entity-form` block
+- Keep pages focused — one primary purpose per page
+
+### Content Block Design
+- Use `fields` arrays to control what's shown (otherwise all fields display)
+- Use `filter` to show related entities (e.g., modules for a course)
+- Use `limit` on home page previews (e.g., 5-6 featured items)
+- Use `"grid"` display for visual content, `"table"` for data-heavy lists
+- Add `actions: ["edit", "delete"]` on detail pages for authorized users
+
+## What NOT to Include
+- Individual field definitions (those come from types blueprint)
+- Form validation rules (those come from entity metadata)
+- Component implementations (the generator creates those)
+- CSS/styling details (the generator applies the theme)
+- API endpoints (the generator creates data loading)
+
+## Built-in Entities Available for Reference
+These can be used in content blocks without defining them in types:
+- **User** — user profile pages, auth-related views
+- **Profile** — user profile display/edit
+
+---
+
+**User Description**: {{USER_DESCRIPTION}}
+
+---
+
+## Response Format
+
+You MUST respond with ONLY a valid JSON object starting with `{ "version": 1, "routes": [...], "pages": { ... } }`.
+
+**CRITICAL REQUIREMENTS**:
+1. Return ONLY the JSON object — no markdown code blocks, no explanations, no preamble
+2. Must include `"version": 1`
+3. Must include `"routes"` array with at least one route
+4. Must include `"pages"` object with a key for every page referenced in routes
+5. Every route `page` value must have a matching key in `pages`
+6. Entity names must be PascalCase (e.g., `"Course"`, not `"course"`)
+7. Page keys must be lowercase-hyphenated (e.g., `"course-detail"`, not `"courseDetail"`)
+8. Do NOT include types, roles, or app blueprint content — UI only
+
+**Common Mistakes to AVOID**:
+- Wrapping response in markdown ```json...``` blocks
+- Including explanatory text before or after the JSON
+- Mismatched route `page` values and `pages` keys
+- Using camelCase for page keys (use lowercase-hyphenated)
+- Using lowercase for entity names (use PascalCase)
+- Defining fields/validation that belongs in the types blueprint
+- Forgetting `access` on routes

package/schemas/app.schema.json

@@ -0,0 +1,289 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://radish.dev/schemas/app.schema.json",
+  "title": "Radish App Blueprint",
+  "description": "Schema for defining application-level metadata, audience, workflows, features, and entity overview. This blueprint drives generation of types.yml, roles.yml, and UI layer blueprints.",
+  "type": "object",
+  "required": [
+    "version",
+    "app"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Blueprint spec version"
+    },
+    "app": {
+      "type": "object",
+      "description": "Core application metadata",
+      "required": [
+        "name",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Application name (PascalCase or camelCase, used for code generation)"
+        },
+        "displayName": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "Human-readable display name"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2000,
+          "description": "Full description of the application purpose and functionality"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Application version (semver format)"
+        },
+        "domain": {
+          "type": "string",
+          "description": "Business domain (e.g., education, e-commerce, healthcare)"
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Searchable tags for categorization"
+        }
+      }
+    },
+    "audience": {
+      "type": "object",
+      "description": "Target audience and user personas",
+      "additionalProperties": false,
+      "properties": {
+        "primary": {
+          "type": "string",
+          "description": "Primary user persona"
+        },
+        "secondary": {
+          "type": "string",
+          "description": "Secondary user persona"
+        },
+        "admin": {
+          "type": "string",
+          "description": "Administrative user persona"
+        }
+      }
+    },
+    "workflows": {
+      "type": "array",
+      "description": "Core user workflows describing what users actually do",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "actor",
+          "description"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Workflow name"
+          },
+          "actor": {
+            "type": "string",
+            "description": "User persona performing this workflow (e.g., student, instructor, admin)"
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Description of the workflow steps and goals"
+          }
+        }
+      }
+    },
+    "categories": {
+      "type": "array",
+      "description": "Content categories and taxonomy",
+      "items": {
+        "type": "object",
+        "required": [
+          "name"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Category name"
+          },
+          "subcategories": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Subcategory names"
+          }
+        }
+      }
+    },
+    "style": {
+      "type": "object",
+      "description": "Style and branding hints for UI generation",
+      "additionalProperties": false,
+      "properties": {
+        "theme": {
+          "type": "string",
+          "description": "Theme name or identifier"
+        },
+        "tone": {
+          "type": "string",
+          "description": "Brand tone (e.g., professional, playful, minimal)"
+        },
+        "palette": {
+          "type": "string",
+          "description": "Color palette description or key colors"
+        },
+        "typography": {
+          "type": "string",
+          "description": "Typography preferences"
+        },
+        "layout": {
+          "type": "string",
+          "description": "Layout style preferences"
+        },
+        "icons": {
+          "type": "string",
+          "description": "Icon style preferences"
+        },
+        "imagery": {
+          "type": "string",
+          "description": "Imagery and placeholder style"
+        }
+      }
+    },
+    "features": {
+      "type": "object",
+      "description": "Feature flags indicating what capabilities this app includes. Additional boolean flags are allowed for future features.",
+      "additionalProperties": {
+        "type": "boolean"
+      },
+      "properties": {
+        "auth": {
+          "type": "boolean",
+          "description": "Authentication system"
+        },
+        "roles": {
+          "type": "boolean",
+          "description": "Role-based access control"
+        },
+        "adminPanel": {
+          "type": "boolean",
+          "description": "Administrative panel"
+        },
+        "api": {
+          "type": "boolean",
+          "description": "REST API endpoints"
+        },
+        "search": {
+          "type": "boolean",
+          "description": "Search functionality"
+        },
+        "pagination": {
+          "type": "boolean",
+          "description": "Paginated lists"
+        },
+        "fileUploads": {
+          "type": "boolean",
+          "description": "File upload capability"
+        },
+        "notifications": {
+          "type": "boolean",
+          "description": "Notification system"
+        },
+        "analytics": {
+          "type": "boolean",
+          "description": "Analytics and reporting"
+        },
+        "scheduling": {
+          "type": "boolean",
+          "description": "Scheduling and calendar features"
+        },
+        "logging": {
+          "type": "boolean",
+          "description": "Application logging"
+        },
+        "cms": {
+          "type": "boolean",
+          "description": "CMS content management (ContentBlock, MediaAsset entities)"
+        },
+        "grants": {
+          "type": "boolean",
+          "description": "Grant-based access control (Grant entity for fine-grained permissions)"
+        }
+      }
+    },
+    "entityOverview": {
+      "type": "object",
+      "description": "High-level entity relationship summary grouped by domain concern. Drives types.yml generation.",
+      "patternProperties": {
+        "^[a-zA-Z][a-zA-Z0-9_]*$": {
+          "type": "array",
+          "description": "Group of related entities (e.g., core, engagement, community)",
+          "items": {
+            "type": "object",
+            "minProperties": 1,
+            "maxProperties": 1,
+            "patternProperties": {
+              "^[A-Z][A-Za-z0-9_]*$": {
+                "type": "string",
+                "description": "Entity name (PascalCase) mapped to a description of its purpose and relationships"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "accessPatterns": {
+      "type": "object",
+      "description": "Access control patterns describing who can see/do what. Drives roles.yml generation.",
+      "patternProperties": {
+        "^[a-zA-Z][a-zA-Z0-9_]*$": {
+          "type": "array",
+          "description": "Access level (e.g., public, authenticated, instructor, admin) mapped to permitted actions",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "database": {
+      "type": "object",
+      "description": "Database configuration",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "mongodb",
+            "postgresql",
+            "mysql"
+          ],
+          "description": "Database engine"
+        },
+        "name": {
+          "type": "string",
+          "description": "Database name"
+        }
+      }
+    }
+  }
+}