@abeedoo/radish-schemas 1.7.7

package/README.md

@@ -0,0 +1,317 @@
+# @radish/schemas
+
+Shared JSON schemas, validators, and AI prompts for the Radish CLI ecosystem.
+
+**All blueprints use JSON as the source of truth.** YAML rendering is available as a display utility.
+
+## Installation
+
+```bash
+npm install @radish/schemas
+```
+
+For GitLab private registry:
+
+```bash
+npm config set @radish:registry https://your-gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/
+npm install @radish/schemas
+```
+
+## Usage
+
+### Validating Blueprints
+
+```javascript
+import { validateBlueprint, formatValidationErrors } from '@radish/schemas';
+import { readFileSync } from 'fs';
+
+const blueprint = JSON.parse(readFileSync('types.json', 'utf8'));
+
+const result = validateBlueprint(blueprint, 'types');
+
+if (result.valid) {
+  console.log('Blueprint is valid');
+} else {
+  console.error(formatValidationErrors(result.errors));
+}
+```
+
+### Validating from Raw JSON Strings
+
+```javascript
+import { validateFromJSON } from '@radish/schemas';
+
+// Parse and validate in one step - useful for AI-generated output
+const result = validateFromJSON(aiResponseString, 'app');
+
+if (result.valid) {
+  console.log('Valid!', result.data); // Parsed object available
+} else {
+  console.error(result.errors); // Includes JSON parse errors
+}
+```
+
+### YAML Display
+
+```javascript
+import { toYAML } from '@radish/schemas';
+
+const blueprint = JSON.parse(readFileSync('app.json', 'utf8'));
+const yamlView = toYAML(blueprint);
+console.log(yamlView);
+// version: 1
+// app:
+//   name: MyApp
+//   description: My application
+```
+
+### Getting Schemas
+
+```javascript
+import { getSchemas, typesSchema, rolesSchema, appSchema } from '@radish/schemas';
+
+// Get all schemas
+const schemas = getSchemas();
+
+// Or import directly
+console.log(typesSchema);
+console.log(rolesSchema);
+console.log(appSchema);
+```
+
+### AI Prompts
+
+```javascript
+import { buildPrompt } from '@radish/schemas/prompts';
+
+// Build a prompt for app blueprint generation
+const appPrompt = buildPrompt('app', 'A blog with posts and comments');
+
+// Build a prompt for types/roles generation
+const typesPrompt = buildPrompt('types', 'A blog with posts and comments');
+```
+
+## Package Structure
+
+```
+@radish/schemas/
+├── schemas/          # JSON Schema files
+│   ├── types.schema.json    # Data layer entities/fields
+│   ├── roles.schema.json    # Roles and permissions
+│   └── app.schema.json      # Application blueprint
+├── validators/       # Validation utilities
+│   └── index.js
+├── prompts/          # AI prompt templates
+│   ├── radish-schema-generation.md   # Types/roles generation
+│   └── radish-app-generation.md      # App blueprint generation
+└── index.js          # Main exports
+```
+
+## Blueprint Types
+
+### types.json
+Data layer entity definitions - fields, relationships, indexes, filters.
+
+### roles.json
+Role and permission definitions for access control.
+
+### app.json
+Application-level blueprint (master document) including:
+- **app** - Name, description, domain, tags
+- **audience** - User personas (primary, secondary, admin)
+- **workflows** - Core user journeys with actors
+- **categories** - Content taxonomy
+- **style** - Branding and UI hints
+- **features** - Feature flags (auth, roles, api, search, etc.)
+- **entityOverview** - High-level entity descriptions grouped by domain concern
+- **accessPatterns** - Who can do what, by access level
+- **database** - Database configuration
+
+## Version Compatibility
+
+### Current Version
+
+- **Package Version:** `@radish/schemas@1.4.0`
+- **Blueprint Spec Version:** `1`
+- **Minimum CLI Version:** `radish-cli@0.1.0`
+
+### Compatibility Policy
+
+`@radish/schemas` follows semantic versioning with special consideration for blueprint compatibility:
+
+- **Major version bumps** (e.g., 1.x → 2.x) indicate **breaking changes to blueprint format**
+- **Minor version bumps** (e.g., 1.0 → 1.1) add **backward-compatible features**
+- **Patch version bumps** (e.g., 1.0.0 → 1.0.1) include **bug fixes and improvements**
+
+For detailed versioning strategy, see [VERSIONING-STRATEGY.md](./VERSIONING-STRATEGY.md).
+
+### Using VERSIONING Metadata
+
+```javascript
+import { VERSIONING } from '@radish/schemas';
+
+console.log(VERSIONING.packageVersion);           // "1.4.0"
+console.log(VERSIONING.currentSpecVersion);       // 1
+console.log(VERSIONING.supportedSpecVersions);    // [1]
+console.log(VERSIONING.minCliVersion);            // "0.1.0"
+```
+
+## API Reference
+
+### Validators
+
+#### `validateBlueprint(data, type)`
+
+Validates a parsed object against a schema.
+
+- **Parameters:**
+  - `data` (object): Parsed JSON data
+  - `type` ('types' | 'roles' | 'app'): Schema type
+- **Returns:** `{ valid: boolean, errors: Array }`
+
+#### `validateFromJSON(jsonString, type)`
+
+Parses a JSON string and validates against a schema.
+
+- **Parameters:**
+  - `jsonString` (string): Raw JSON string
+  - `type` ('types' | 'roles' | 'app'): Schema type
+- **Returns:** `{ valid: boolean, errors: Array, data: object|null }`
+
+#### `toYAML(data)`
+
+Converts a blueprint object to YAML string for display purposes.
+
+- **Parameters:**
+  - `data` (object): Blueprint data
+- **Returns:** `string` - YAML-formatted string
+
+#### `formatValidationErrors(errors)`
+
+Formats AJV errors for display.
+
+- **Parameters:**
+  - `errors` (Array): AJV validation errors
+- **Returns:** `string` - Formatted error message
+
+#### `getSchemas()`
+
+Gets all schemas.
+
+- **Returns:** `{ types: object, roles: object, app: object }`
+
+### Prompts
+
+#### `getSchemaPrompt()`
+
+Gets the AI prompt template for types/roles generation.
+
+- **Returns:** `string` - Prompt markdown
+
+#### `getAppPrompt()`
+
+Gets the AI prompt template for app blueprint generation.
+
+- **Returns:** `string` - Prompt markdown
+
+#### `buildPrompt(promptType, description)`
+
+Builds a complete prompt with user description injected.
+
+- **Parameters:**
+  - `promptType` ('app' | 'types' | 'roles'): Blueprint type to generate
+  - `description` (string): User's app description
+- **Returns:** `string` - Complete prompt
+
+#### `getSchemaForPrompt(type)`
+
+Gets a schema as a JSON string for inclusion in prompts.
+
+- **Parameters:**
+  - `type` ('types' | 'roles' | 'app'): Schema type
+- **Returns:** `string` - Stringified JSON schema
+
+## Validation Service
+
+This package includes a standalone Fastify validation service deployed at `https://schemas.radishplatform.com`.
+
+All Radish tools (wizard, n8n workflows, CLI) use this service as the single source of truth for validation.
+
+### Live URL
+
+`https://schemas.radishplatform.com`
+
+### Running Locally
+
+```bash
+npm start
+# Server starts on http://localhost:3000
+```
+
+### Endpoints
+
+#### `GET /health`
+Returns service status and version info.
+```bash
+curl https://schemas.radishplatform.com/health
+```
+Returns: `{ "status": "ok", "version": "1.4.0", "specVersion": 1, "supportedSpecVersions": [1] }`
+
+#### `POST /validate`
+Validates a parsed JSON object.
+```bash
+curl -X POST https://schemas.radishplatform.com/validate \
+  -H "Content-Type: application/json" \
+  -d '{"type": "app", "data": {"version": 1, "app": {"name": "Test", "description": "A test"}}}'
+```
+Returns: `{ "valid": true|false, "errors": [...], "data": {...}, "formatted": "..." }`
+
+#### `POST /validate/json`
+Parses a raw JSON string and validates (ideal for AI output).
+```bash
+curl -X POST https://schemas.radishplatform.com/validate/json \
+  -H "Content-Type: application/json" \
+  -d '{"type": "types", "json": "{\"version\":1,\"entities\":{...}}"}'
+```
+Returns: `{ "valid": true|false, "errors": [...], "data": {...}, "formatted": "..." }`
+
+#### `GET /schemas/:type`
+Returns the raw JSON schema for `app`, `types`, or `roles`.
+```bash
+curl https://schemas.radishplatform.com/schemas/app
+```
+
+#### `POST /prompts/:type`
+Returns an AI prompt with user description injected. Types: `app`, `types`, `roles`.
+```bash
+curl -X POST https://schemas.radishplatform.com/prompts/app \
+  -H "Content-Type: application/json" \
+  -d '{"description": "A blog with posts and comments"}'
+```
+Returns: `{ "prompt": "..." }`
+
+#### `GET /prompts/:type`
+Returns the raw prompt template (with `{{USER_DESCRIPTION}}` placeholder).
+```bash
+curl https://schemas.radishplatform.com/prompts/types
+```
+
+#### `POST /to-yaml`
+Converts a JSON object to YAML for display.
+```bash
+curl -X POST https://schemas.radishplatform.com/to-yaml \
+  -H "Content-Type: application/json" \
+  -d '{"version": 1, "app": {"name": "Blog", "description": "A blog"}}'
+```
+Returns: `{ "yaml": "..." }`
+
+### Docker Deployment
+
+```bash
+docker build -t radish-schemas .
+docker run -p 3000:3000 radish-schemas
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,38 @@
+// Main entry point for @radish/schemas
+export { typesSchema, rolesSchema, appSchema, uiSchema, componentsSchema, themeSchema, getSchema } from './schemas/index.js';
+export {
+  validateBlueprint,
+  validateFromJSON,
+  toYAML,
+  getSchemas,
+  formatValidationErrors,
+  validators
+} from './validators/index.js';
+export {
+  getTypesPrompt,
+  getRolesPrompt,
+  getAppPrompt,
+  getUiPrompt,
+  getComponentsPrompt,
+  getThemePrompt,
+  getSchemaPrompt,  // deprecated: use getTypesPrompt/getRolesPrompt
+  buildPrompt,
+  getSchemaForPrompt
+} from './prompts/index.js';
+
+/**
+ * Version metadata for @radish/schemas
+ *
+ * This provides compatibility information for tools and CLIs that depend on this package.
+ *
+ * @property {string} packageVersion - The npm package version (from package.json)
+ * @property {number} currentSpecVersion - The current blueprint format version
+ * @property {number[]} supportedSpecVersions - All blueprint format versions supported by this package
+ * @property {string} minCliVersion - Minimum radish-cli version compatible with this package
+ */
+export const VERSIONING = {
+  packageVersion: '1.7.7',
+  currentSpecVersion: 1,
+  supportedSpecVersions: [1],
+  minCliVersion: '0.1.0'
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@abeedoo/radish-schemas",
+  "version": "1.7.7",
+  "description": "Shared JSON schemas, validators, and prompts for Radish CLI ecosystem",
+  "main": "index.js",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./schemas": "./schemas/index.js",
+    "./validators": "./validators/index.js",
+    "./prompts": "./prompts/index.js",
+    "./schemas/types.schema.json": "./schemas/types.schema.json",
+    "./schemas/roles.schema.json": "./schemas/roles.schema.json",
+    "./schemas/app.schema.json": "./schemas/app.schema.json",
+    "./schemas/ui.schema.json": "./schemas/ui.schema.json",
+    "./schemas/components.schema.json": "./schemas/components.schema.json",
+    "./schemas/theme.schema.json": "./schemas/theme.schema.json"
+  },
+  "files": [
+    "schemas/",
+    "validators/",
+    "prompts/",
+    "types/",
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test.js",
+    "start": "node server/index.js",
+    "prepublishOnly": "echo 'Running pre-publish checks...'"
+  },
+  "keywords": [
+    "radish",
+    "schema",
+    "validation",
+    "blueprints"
+  ],
+  "author": "Radish CLI",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^2.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/prompts/index.js

@@ -0,0 +1,118 @@
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { getSchema } from '../schemas/index.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Get the AI types blueprint generation prompt
+ * @returns {string} Prompt markdown content
+ */
+export function getTypesPrompt() {
+  return readFileSync(
+    join(__dirname, 'radish-types-generation.md'),
+    'utf-8'
+  );
+}
+
+/**
+ * Get the AI roles blueprint generation prompt
+ * @returns {string} Prompt markdown content
+ */
+export function getRolesPrompt() {
+  return readFileSync(
+    join(__dirname, 'radish-roles-generation.md'),
+    'utf-8'
+  );
+}
+
+/**
+ * Get the AI UI blueprint generation prompt
+ * @returns {string} Prompt markdown content
+ */
+export function getUiPrompt() {
+  return readFileSync(
+    join(__dirname, 'radish-ui-generation.md'),
+    'utf-8'
+  );
+}
+
+/**
+ * Get the AI components blueprint generation prompt
+ * @returns {string} Prompt markdown content
+ */
+export function getComponentsPrompt() {
+  return readFileSync(
+    join(__dirname, 'radish-components-generation.md'),
+    'utf-8'
+  );
+}
+
+/**
+ * Get the AI theme blueprint generation prompt
+ * @returns {string} Prompt markdown content
+ */
+export function getThemePrompt() {
+  return readFileSync(
+    join(__dirname, 'radish-theme-generation.md'),
+    'utf-8'
+  );
+}
+
+/**
+ * Get the AI app blueprint generation prompt
+ * @returns {string} Prompt markdown content
+ */
+export function getAppPrompt() {
+  return readFileSync(
+    join(__dirname, 'radish-app-generation.md'),
+    'utf-8'
+  );
+}
+
+/**
+ * @deprecated Use getTypesPrompt() or getRolesPrompt() instead.
+ * Returns the combined types+roles prompt for backward compatibility.
+ * @returns {string} Prompt markdown content
+ */
+export function getSchemaPrompt() {
+  return readFileSync(
+    join(__dirname, 'radish-schema-generation.md'),
+    'utf-8'
+  );
+}
+
+/**
+ * Build a complete prompt with user description injected
+ * @param {'app' | 'types' | 'roles' | 'ui' | 'components' | 'theme'} promptType - Blueprint type to generate
+ * @param {string} description - User's app description
+ * @returns {string} Complete prompt with description injected
+ */
+export function buildPrompt(promptType, description) {
+  const prompts = {
+    app: getAppPrompt,
+    types: getTypesPrompt,
+    roles: getRolesPrompt,
+    ui: getUiPrompt,
+    components: getComponentsPrompt,
+    theme: getThemePrompt
+  };
+
+  const getPrompt = prompts[promptType];
+  if (!getPrompt) {
+    throw new Error(`Unknown prompt type: ${promptType}. Available: ${Object.keys(prompts).join(', ')}`);
+  }
+
+  return getPrompt().replace('{{USER_DESCRIPTION}}', description);
+}
+
+/**
+ * Get schema JSON for inclusion in prompts
+ * @param {'types' | 'roles' | 'app'} type - Schema type
+ * @returns {string} Stringified JSON schema
+ */
+export function getSchemaForPrompt(type) {
+  return JSON.stringify(getSchema(type), null, 2);
+}