@specverse/engine-realize 3.5.3

package/libs/instance-factories/CURVED-INTERFACE.md

@@ -0,0 +1,278 @@
+# CURVED Interface Standard
+
+## Overview
+
+**CURVED** is the standard interface that all SpecVerse business logic controllers must implement. It defines the complete set of operations for managing domain models.
+
+## CURVED Operations
+
+| Letter | Operation | Description | Required |
+|--------|-----------|-------------|----------|
+| **C** | Create | Create a new entity | Yes |
+| **U** | Update | Update an existing entity | Yes |
+| **R** | Retrieve | Retrieve entity (single + list) | Yes |
+| **V** | Validate | Validate data before operations | Yes |
+| **E** | Evolve | Lifecycle-aware state transitions | Yes |
+| **D** | Delete | Delete an entity | Yes |
+
+## TypeScript Interface
+
+```typescript
+/**
+ * Standard CURVED interface for all service controllers
+ * All business logic controllers must implement this interface
+ */
+interface CurvedController<T> {
+  // C - Create
+  create(data: any): Promise<T>;
+
+  // U - Update
+  update(id: string, data: any): Promise<T>;
+
+  // R - Retrieve (single)
+  retrieve(id: string): Promise<T>;
+
+  // R - Retrieve (list)
+  retrieveAll(options?: RetrieveOptions): Promise<T[]>;
+
+  // V - Validate
+  validate(
+    data: any,
+    context: { operation: 'create' | 'update' | 'evolve' }
+  ): ValidationResult;
+
+  // E - Evolve (lifecycle-aware updates)
+  evolve(id: string, data: any): Promise<T>;
+
+  // D - Delete
+  delete(id: string): Promise<void>;
+}
+
+interface RetrieveOptions {
+  skip?: number;
+  take?: number;
+  where?: Record<string, any>;
+  orderBy?: Record<string, 'asc' | 'desc'>;
+  include?: string[];
+}
+
+interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+```
+
+## Architecture Layers
+
+### 1. Controllers (Model-specific)
+- **Must implement**: Full CURVED interface
+- **Examples**: `UserController`, `ProjectController`, `TaskController`
+- **Location**: `src/controllers/`
+- **Generated by**: Service factories (PrismaServices, TypeORMServices, etc.)
+- **Additional**: Can have custom actions beyond CURVED
+
+```yaml
+# In SpecVerse spec
+controllers:
+  UserController:
+    model: User
+    curved:               # ← CURVED operations
+      create: {}
+      update: {}
+      retrieve: {}
+      validate: {}
+      evolve: {}
+      delete: {}
+    actions:              # ← Custom actions (beyond CURVED)
+      resetPassword: {}
+      verifyEmail: {}
+```
+
+### 2. Services (Abstract business logic)
+- **Must implement**: Custom operations (NOT CURVED)
+- **Examples**: `NotificationService`, `TaskAssignmentService`
+- **Location**: `src/services/`
+- **Generated by**: Service factories (PrismaServices, etc.)
+- **Operations**: Custom business logic operations
+
+```yaml
+# In SpecVerse spec
+services:
+  NotificationService:
+    operations:           # ← Custom operations (NOT CURVED)
+      sendWelcomeEmail: {}
+      sendPasswordReset: {}
+```
+
+### 3. Storage/ORM Layer
+- **Must support**: CURVED primitives
+- **Examples**: Prisma client, TypeORM repositories, Mongoose models
+- **Location**: ORM-specific (e.g., `prisma/schema.prisma`)
+- **Generated by**: ORM factories (PrismaORM, TypeORM, Mongoose)
+- **Provides**: Database access methods that enable CURVED operations
+
+## Implementation Requirements
+
+### All Service Factories Must:
+
+1. **Generate controllers** that implement the full CURVED interface
+2. **Support all CURVED operations** for every model
+3. **Provide consistent signatures** across different ORMs
+4. **Include validation** as part of the CURVED interface
+5. **Support evolve** for lifecycle-aware updates
+
+### Example Implementations:
+
+#### PrismaServices
+- Uses: `@prisma/client`
+- Controllers: `src/controllers/{Model}Controller.ts`
+- Pattern: Class-based with Prisma client calls
+
+#### TypeORMServices (future)
+- Uses: `typeorm` repositories
+- Controllers: `src/controllers/{Model}Controller.ts`
+- Pattern: Class-based with TypeORM repository calls
+
+#### MongooseServices (future)
+- Uses: `mongoose` models
+- Controllers: `src/controllers/{Model}Controller.ts`
+- Pattern: Class-based with Mongoose model calls
+
+## Data Flow
+
+```
+API Layer (Fastify/SOAP/GraphQL)
+    ↓ calls
+    ├─→ Controllers (CURVED + actions)
+    │       ↓ calls
+    │   Storage/ORM (CURVED primitives)
+    │       ↓
+    │   Database
+    │
+    └─→ Services (custom operations)
+            ↓ can call
+            ├─→ Controllers (CURVED)
+            └─→ Storage/ORM (directly)
+```
+
+**Key points:**
+- API layer can call **both** Controllers and Services
+- Services can call Controllers OR ORM directly
+- Controllers always call ORM/Storage layer
+
+## Validation in CURVED
+
+The **V** (Validate) operation is special:
+
+### Internal Validation
+All CURVED operations internally call `validate()` before execution:
+
+```typescript
+async create(data: any): Promise<T> {
+  // Internal validation
+  const validation = this.validate(data, { operation: 'create' });
+  if (!validation.valid) {
+    throw new Error(`Validation failed: ${validation.errors.join(', ')}`);
+  }
+
+  // Proceed with creation
+  return await this.orm.create(data);
+}
+```
+
+### External Validation
+The validate operation can also be exposed as an API endpoint for dry-run validation:
+
+```typescript
+// POST /api/users/validate
+{
+  "data": { "email": "invalid", "name": "John" },
+  "operation": "create"
+}
+
+// Response
+{
+  "valid": false,
+  "errors": ["email must be a valid email address"]
+}
+```
+
+## Evolve vs Update
+
+### Update
+Standard field updates without lifecycle validation:
+```typescript
+// Update any field
+await userController.update(userId, { name: 'New Name', email: 'new@email.com' });
+```
+
+### Evolve
+Lifecycle-aware state transitions with validation:
+```typescript
+// Evolve through lifecycle states
+await taskController.evolve(taskId, {
+  status: 'in_progress'  // Must follow lifecycle: todo → in_progress
+});
+```
+
+## Extension Points
+
+While CURVED defines the core interface, controllers can extend it with:
+
+1. **Custom Actions** - Additional operations specific to the model
+2. **Event Publishing** - Emit events after CURVED operations
+3. **Hooks** - Before/after hooks for operations
+4. **Caching** - Add caching layer for retrieve operations
+5. **Authorization** - Add permission checks before operations
+
+## Testing CURVED Implementations
+
+All service factories should provide tests verifying:
+
+```typescript
+describe('CurvedController', () => {
+  it('implements create operation', async () => {
+    const result = await controller.create(validData);
+    expect(result).toBeDefined();
+  });
+
+  it('implements update operation', async () => {
+    const result = await controller.update(id, updateData);
+    expect(result).toBeDefined();
+  });
+
+  it('implements retrieve operation', async () => {
+    const result = await controller.retrieve(id);
+    expect(result).toBeDefined();
+  });
+
+  it('implements retrieveAll operation', async () => {
+    const result = await controller.retrieveAll();
+    expect(Array.isArray(result)).toBe(true);
+  });
+
+  it('implements validate operation', async () => {
+    const result = controller.validate(data, { operation: 'create' });
+    expect(result).toHaveProperty('valid');
+    expect(result).toHaveProperty('errors');
+  });
+
+  it('implements evolve operation', async () => {
+    const result = await controller.evolve(id, evolveData);
+    expect(result).toBeDefined();
+  });
+
+  it('implements delete operation', async () => {
+    await expect(controller.delete(id)).resolves.not.toThrow();
+  });
+});
+```
+
+## Summary
+
+**CURVED is the universal interface for all SpecVerse business logic controllers:**
+- Ensures consistency across different ORMs (Prisma, TypeORM, Mongoose)
+- Enables protocol-agnostic API layers (REST, SOAP, GraphQL, gRPC)
+- Provides complete lifecycle management (Create, Update, Retrieve, Validate, Evolve, Delete)
+- Separates concerns between Controllers (model-specific) and Services (abstract)
+- Supports extension while maintaining core interface compatibility

package/libs/instance-factories/README.md

@@ -0,0 +1,433 @@
+# SpecVerse v3.3 Implementation Types System
+
+**Revolutionary manifest-driven code generation with reusable implementation libraries**
+
+## Overview
+
+The Implementation Types System separates **WHAT** (component specification) from **WHERE** (deployment topology) and **HOW** (technology implementation), enabling:
+
+- 📦 **Reusable Tech Stacks** - Share implementation patterns across projects
+- 🔄 **Technology Flexibility** - Swap implementations without changing specs
+- 🚀 **Rapid Development** - Generate production-ready code in seconds
+- 🌍 **Community-Driven** - Build and share implementation libraries
+
+## Quick Start
+
+### 1. Define Your Implementation Type
+
+```yaml
+# libs/instance-factories/backend/fastify-prisma.yaml
+name: FastifyPrismaAPI
+version: "1.0.0"
+type: api-server
+
+capabilities:
+  provides:
+    - "api.rest"
+    - "api.rest.crud"
+  requires: []
+
+technology:
+  runtime: "node"
+  framework: "fastify"
+  orm: "prisma"
+
+codeTemplates:
+  routes:
+    engine: typescript
+    generator: "libs/instance-factories/backend/templates/fastify/routes-generator.ts"
+    outputPattern: "routes/{controller}.ts"
+
+  services:
+    engine: typescript
+    generator: "libs/instance-factories/backend/templates/prisma/services-generator.ts"
+    outputPattern: "services/{model}.service.ts"
+```
+
+### 2. Create Your Manifest
+
+```yaml
+# manifest.yaml
+specVersion: "3.3.0"
+version: "1.0.0"
+name: "my-api-project"
+
+implementationTypes:
+  - name: "FastifyPrismaAPI"
+    source: "libs/instance-factories/backend/fastify-prisma.yaml"
+    version: "1.0.0"
+
+capabilityMappings:
+  - capability: "api.rest"
+    implementationType: "FastifyPrismaAPI"
+```
+
+### 3. Define Your Spec with Deployment
+
+```yaml
+# spec.specly
+components:
+  MyAPI:
+    version: "1.0.0"
+    models:
+      User:
+        attributes:
+          id: UUID required
+          name: String required
+          email: String required
+
+deployments:
+  production:
+    version: "1.0.0"
+    environment: production
+    instances:
+      apiServer:
+        type: api-server
+        advertises: ["api.rest"]
+```
+
+### 4. Generate Code
+
+```bash
+specverse realize all spec.specly -m manifest.yaml -o generated/
+```
+
+## Architecture
+
+### Three-Layer System
+
+```
+┌─────────────────────────┐
+│   SPECIFICATION         │  Define WHAT you need
+│   (spec.specly)         │
+└───────────┬─────────────┘
+            │
+            ↓
+┌─────────────────────────┐
+│   DEPLOYMENT            │  Define WHERE it runs
+│   (in spec)             │
+└───────────┬─────────────┘
+            │
+            ↓
+┌─────────────────────────┐
+│   MANIFEST              │  Map HOW to implement
+│   (manifest.yaml)       │
+└───────────┬─────────────┘
+            │
+            ↓
+┌─────────────────────────┐
+│   IMPLEMENTATION TYPE   │  Defines tech stack
+│   (fastify-prisma.yaml) │
+└───────────┬─────────────┘
+            │
+            ↓
+┌─────────────────────────┐
+│   GENERATED CODE        │  Production-ready code
+└─────────────────────────┘
+```
+
+## Implementation Type Structure
+
+### Required Fields
+
+```yaml
+name: String              # Unique name (e.g., "FastifyPrismaAPI")
+version: String           # Semantic version (e.g., "1.0.0")
+type: String              # Type category (api-server, database, etc.)
+description: String       # Human-readable description
+
+compatibility:
+  specverse: String       # Compatible SpecVerse version (e.g., "^3.3.0")
+  node: String           # Required Node.js version (optional)
+
+capabilities:
+  provides: String[]      # Capabilities this implementation provides
+  requires: String[]      # Capabilities this implementation needs
+
+technology:
+  runtime: String         # Runtime environment (node, deno, browser)
+  language: String        # Programming language (typescript, javascript)
+  framework: String       # Primary framework (fastify, express, react)
+
+dependencies:
+  runtime: Array          # Runtime dependencies
+    - name: String
+      version: String
+  dev: Array             # Dev dependencies
+    - name: String
+      version: String
+
+codeTemplates:
+  [name]: Object          # Named code templates
+    engine: String        # "typescript" | "handlebars" | "ai"
+    generator: String     # Path to generator function
+    outputPattern: String # Output file pattern with variables
+```
+
+### Capability Patterns
+
+Capabilities follow a hierarchical pattern:
+
+- `api.rest` - Basic REST API
+- `api.rest.crud` - REST API with CRUD operations
+- `api.graphql` - GraphQL API
+- `storage.database` - Generic database
+- `storage.prisma` - Prisma ORM
+- `storage.typeorm` - TypeORM
+- `cache.redis` - Redis caching
+- `queue.rabbitmq` - RabbitMQ messaging
+
+## Template Generators
+
+### TypeScript Generator Example
+
+```typescript
+// templates/fastify/routes-generator.ts
+import type { TemplateContext } from '../../../src/realize/types/index.js';
+
+export default function generateFastifyRoutes(context: TemplateContext): string {
+  const { controller, model } = context;
+
+  return `
+import { FastifyInstance } from 'fastify';
+import { ${model.name}Service } from '../services/${model.name}.service.js';
+
+export default async function ${controller.name}Routes(
+  fastify: FastifyInstance
+) {
+  const service = new ${model.name}Service(fastify.prisma);
+
+  // Create
+  fastify.post('/', async (request, reply) => {
+    const result = await service.create(request.body);
+    return reply.status(201).send(result);
+  });
+
+  // Retrieve
+  fastify.get('/:id', async (request, reply) => {
+    const { id } = request.params as { id: string };
+    const result = await service.retrieve(id);
+    return reply.send(result);
+  });
+}
+`;
+}
+```
+
+### Template Context
+
+The `TemplateContext` provides:
+
+```typescript
+{
+  spec: AIOptimizedSpec;           // Full specification
+  model?: any;                     // Current model
+  controller?: any;                // Current controller
+  service?: any;                   // Current service
+  implType: ImplementationType;    // Implementation type
+  instance: any;                   // Deployment instance
+  [key: string]: any;              // Additional context
+}
+```
+
+## Manifest Format
+
+### v3.3 Manifest
+
+```yaml
+specVersion: "3.3.0"    # Required: SpecVerse version
+version: "1.0.0"        # Required: Manifest version
+name: "project-name"    # Required: Project name
+
+implementationTypes:    # Array of implementation type references
+  - name: "FastifyPrismaAPI"
+    source: "path/to/fastify-prisma.yaml"
+    version: "1.0.0"
+
+capabilityMappings:     # Array of capability → implementation mappings
+  - capability: "api.rest"
+    implementationType: "FastifyPrismaAPI"
+  - capability: "storage.database"
+    implementationType: "PostgreSQLDatabase"
+
+configuration:          # Global configuration (optional)
+  environment: production
+  logLevel: info
+```
+
+## Creating New Implementation Types
+
+### Step 1: Define Technology Stack
+
+Identify:
+- Framework and libraries
+- Dependencies and versions
+- Capabilities provided/required
+- Code templates needed
+
+### Step 2: Create YAML Definition
+
+```yaml
+name: YourImplementation
+version: "1.0.0"
+type: api-server
+# ... (see structure above)
+```
+
+### Step 3: Write Template Generators
+
+Create TypeScript functions that generate code:
+
+```typescript
+export default function generateYourCode(context: TemplateContext): string {
+  // Generate code based on context
+  return generatedCode;
+}
+```
+
+### Step 4: Test
+
+```bash
+# Test your implementation type
+npx tsx libs/instance-factories/test-v33-generation.ts
+```
+
+## Examples
+
+### Available Implementation Types
+
+- **FastifyPrismaAPI** (`backend/fastify-prisma.yaml`)
+  - Fastify web server
+  - Prisma ORM
+  - Zod validation
+  - JWT authentication
+  - Provides: `api.rest`, `api.rest.crud`
+
+### Example Manifests
+
+- **fastify-prisma-manifest.yaml** - Full-stack API with Fastify + Prisma
+
+## CLI Integration
+
+### Generate Code with v3.3
+
+```bash
+# Realize all code types
+specverse realize all spec.specly -m manifest.yaml -o generated/
+
+# Realize specific types
+specverse realize routes spec.specly -m manifest.yaml -o generated/routes
+specverse realize services spec.specly -m manifest.yaml -o generated/services
+```
+
+## Development
+
+### Project Structure
+
+```
+libs/instance-factories/
+├── README.md                    # This file
+├── backend/
+│   ├── fastify-prisma.yaml     # Implementation type definition
+│   └── templates/
+│       ├── fastify/
+│       │   └── routes-generator.ts
+│       └── prisma/
+│           ├── services-generator.ts
+│           └── schema-generator.ts
+├── test-v33-generation.ts      # End-to-end test
+└── examples/                    # Example specs and manifests
+```
+
+### Testing
+
+```bash
+# Run end-to-end test
+npx tsx libs/instance-factories/test-v33-generation.ts
+
+# Run with custom spec
+npx tsx libs/instance-factories/test-v33-generation.ts path/to/spec.specly
+```
+
+## Best Practices
+
+### Implementation Types
+
+1. **Single Responsibility** - Each implementation type should have one clear purpose
+2. **Version Carefully** - Use semantic versioning for compatibility
+3. **Document Capabilities** - Clearly define what capabilities are provided
+4. **Test Thoroughly** - Test all templates with various specs
+
+### Manifests
+
+1. **Explicit Mappings** - Map all used capabilities explicitly
+2. **Version Lock** - Specify exact versions for reproducibility
+3. **Environment-Specific** - Use different manifests for dev/prod
+4. **Validate** - Always validate manifests before deployment
+
+### Templates
+
+1. **Type Safety** - Use TypeScript for template generators
+2. **Error Handling** - Handle missing context gracefully
+3. **Formatting** - Generate clean, formatted code
+4. **Comments** - Add helpful comments to generated code
+
+## Troubleshooting
+
+### Common Issues
+
+**Implementation type not found**
+```
+Solution: Check the source path in manifestation implementationTypes
+```
+
+**Capability not resolved**
+```
+Solution: Ensure capability mapping exists in manifest
+```
+
+**Template generator fails**
+```
+Solution: Check template path is correct and generator exports default function
+```
+
+**Generated code has errors**
+```
+Solution: Verify template context has all required data
+```
+
+## Contributing
+
+We welcome contributions of new implementation types!
+
+### Guidelines
+
+1. Follow the structure defined in this README
+2. Include comprehensive tests
+3. Document all capabilities clearly
+4. Provide example manifests
+5. Use TypeScript for generators
+
+### Submission Process
+
+1. Create implementation type YAML
+2. Write template generators
+3. Test end-to-end
+4. Submit pull request with documentation
+
+## Resources
+
+- **Implementation Plan**: `docs/implementation-plans/v3.3-implementation/IMPLEMENTATION-TYPES-SYSTEM-PLAN.md`
+- **Schema**: `schema/IMPLEMENTATION-TYPE-SCHEMA.json`
+- **Examples**: `examples/v33-test/`
+- **Core Types**: `src/realize/types/implementation-type.ts`
+
+## License
+
+MIT License - see LICENSE file for details
+
+---
+
+**Status**: ✅ Production Ready (v3.3.0)
+
+Built with ❤️ by the SpecVerse Team