@specverse/engines 4.2.0 → 4.2.1

package/assets/templates/default/specs/main.specly

@@ -0,0 +1,65 @@
+# Starter specification.
+#
+# Two models, one belongsTo relationship, one lifecycle. Small enough
+# to read in 30 seconds, rich enough to exercise the generated-UI
+# rules you'll build on: lifecycle dropdowns, belongsTo FK dropdowns,
+# FK resolution in list / detail / dashboard columns.
+components:
+  {{componentName}}:
+    version: "1.0.0"
+    description: "Starter specification — use the AI tab to extend it"
+    tags: [default, minimal]
+
+    models:
+      Category:
+        description: "A grouping label for Items"
+        attributes:
+          id: UUID required auto=uuid4
+          name: String required unique
+          description: Text
+          createdAt: DateTime auto=now
+          updatedAt: DateTime auto=now
+        relationships:
+          items: hasMany Item
+
+      Item:
+        description: "Something worth tracking"
+        attributes:
+          id: UUID required auto=uuid4
+          name: String required
+          description: Text
+          status: String required default=active
+          createdAt: DateTime auto=now
+          updatedAt: DateTime auto=now
+        relationships:
+          category: belongsTo Category
+        lifecycles:
+          status:
+            flow: "active -> archived"
+
+    views:
+      CategoryListView:
+        type: list
+        model: Category
+      CategoryDetailView:
+        type: detail
+        model: Category
+      CategoryFormView:
+        type: form
+        model: Category
+      CategoryDashboardView:
+        type: dashboard
+        model: Category
+
+      ItemListView:
+        type: list
+        model: Item
+      ItemDetailView:
+        type: detail
+        model: Item
+      ItemFormView:
+        type: form
+        model: Item
+      ItemDashboardView:
+        type: dashboard
+        model: Item

package/dist/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/dist/libs/instance-factories/README.md

@@ -0,0 +1,73 @@
+# Instance Factories
+
+Code generation templates for the realize engine. Each factory category produces a specific kind of output from a SpecVerse specification.
+
+## Factory Categories
+
+| Category | Templates | Generates |
+|----------|-----------|-----------|
+| [applications](applications/) | generic, react | App scaffolding, React frontend (API client, views, routing, sidebar) |
+| [cli](cli/) | commander | CLI entry point, command files from spec commands |
+| [communication](communication/) | eventemitter | Event bus, publishers, subscribers |
+| [controllers](controllers/) | fastify | Fastify route handlers, server with auto-wired routes |
+| [infrastructure](infrastructure/) | docker-k8s | Dockerfiles, docker-compose, Kubernetes manifests |
+| [orms](orms/) | prisma | Prisma schema from models (relations, types, defaults) |
+| [scaffolding](scaffolding/) | generic | package.json, tsconfig, .env, .gitignore, README |
+| [sdks](sdks/) | python, typescript | Client SDKs for generated APIs |
+| [services](services/) | prisma | CURVED controllers, business logic services, behavior generation |
+| [storage](storage/) | mongodb, postgresql, redis | Database configs, Docker setup |
+| [testing](testing/) | vitest | Test file generation |
+| [tools](tools/) | mcp, vscode | MCP server, VSCode extension (14 commands) |
+| [validation](validation/) | zod | Zod validation schemas from model attributes |
+| [views](views/) | react, shared | React components (list, detail, form, dashboard), adapters |
+| [shared](shared/) | - | Path resolver, reserved words |
+| [archived](archived/) | - | Deprecated factory definitions |
+
+## How It Works
+
+```
+Specification + Manifest
+        |
+        v
+  [Manifest Loader] ---> resolve capabilities to factories
+        |
+        v
+  [Instance Factory Library] ---> find matching factory YAML
+        |
+        v
+  [Code Generator] ---> call template generator function
+        |
+        v
+  Generated source file
+```
+
+Each factory has:
+1. **YAML definition** — declares capabilities, technology, and template mappings
+2. **Template generators** — TypeScript functions that produce source code from spec context
+
+## Template Generator Pattern
+
+Every generator is a function that receives spec context and returns source code:
+
+```typescript
+export function generate(context: {
+  spec: any;          // Full SpecVerseAST
+  model?: any;        // Current model (if model-scoped)
+  controller?: any;   // Current controller
+  models?: any[];     // All models in component
+  componentName: string;
+}): { filePath: string; code: string } {
+  // Generate and return source code
+}
+```
+
+## Adding a New Factory
+
+1. Create a YAML definition in the appropriate category
+2. Write template generator(s) in `templates/{technology}/`
+3. The realize engine discovers factories by scanning this directory
+
+## See Also
+
+- [Realize Engine README](../../README.md)
+- [Architecture Guide](https://github.com/SpecVerse/specverse-self/blob/main/docs/guides/ARCHITECTURE-GUIDE.md)

package/dist/libs/instance-factories/applications/README.md

@@ -0,0 +1,51 @@
+# Applications Factory
+
+Full application scaffolding for backend and frontend entry points.
+
+## Definitions
+
+| File | Description |
+|------|-------------|
+| `generic-app.yaml` | Backend entry point — adapts to framework choice (defaults to Fastify) |
+| `react-app.yaml` | Complete React SPA with Vite, React Router, and TanStack Query |
+
+## Generated Output
+
+### Generic Backend (`generic/`)
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `main-generator` | `backend/src/main.ts` | Application entry point (detects framework from manifest) |
+| `backend-package-json-generator` | `backend/package.json` | Backend dependencies and scripts |
+| `backend-tsconfig-generator` | `backend/tsconfig.json` | TypeScript configuration |
+| `backend-env-generator` | `backend/.env` | Environment variables |
+
+### React Frontend (`react/`)
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `app-tsx-generator` | `frontend/src/App.tsx` | Root component with sidebar navigation grouped by model |
+| `main-tsx-generator` | `frontend/src/main.tsx` | React DOM render entry |
+| `vite-config-generator` | `frontend/vite.config.ts` | Vite bundler config with API proxy |
+| `package-json-generator` | `frontend/package.json` | Frontend dependencies |
+| `tsconfig-generator` | `frontend/tsconfig.json` | TypeScript config |
+| `index-html-generator` | `frontend/index.html` | HTML shell |
+| `index-css-generator` | `frontend/src/index.css` | Base styles |
+| `api-client-generator` | `frontend/src/lib/apiClient.ts` | HTTP client for backend API |
+| `api-types-generator` | `frontend/src/types/api.ts` | TypeScript types from spec models |
+| `use-api-hooks-generator` | `frontend/src/hooks/useApi.ts` | React Query data-fetching hooks |
+| `view-list-generator` | `frontend/src/components/views/ListView.tsx` | List view component |
+| `view-detail-generator` | `frontend/src/components/views/DetailView.tsx` | Detail view component |
+| `view-form-generator` | `frontend/src/components/views/FormView.tsx` | Form view component |
+| `view-dashboard-generator` | `frontend/src/components/views/DashboardView.tsx` | Dashboard view component |
+| `view-router-generator` | `frontend/src/components/views/StandardViewRouter.tsx` | View routing |
+| `pattern-adapter-generator` | `frontend/src/lib/react-pattern-adapter.tsx` | Pattern adapter for dynamic rendering |
+| `tailwind-adapter-wrapper-generator` | `frontend/src/lib/tailwind-adapter-generator.ts` | Tailwind CSS adapter |
+| `field-helpers-generator` | `frontend/src/utils/field-helpers.ts` | Form field utilities |
+| `relationship-field-generator` | `frontend/src/components/fields/RelationshipField.tsx` | Relationship field component |
+
+## Technology
+
+- **Backend**: Node.js, TypeScript, Fastify (default)
+- **Frontend**: React 18, Vite 5, React Router 6, TanStack Query 5
+- **Structure**: Monorepo (`backend/` + `frontend/`)

package/dist/libs/instance-factories/applications/generic-app.yaml

@@ -0,0 +1,52 @@
+name: GenericApp
+version: "1.0.0"
+category: application
+description: "Generic application entry point that adapts to framework choice"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [application, entry-point, generic]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "app.entrypoint"
+    - "app.main"
+  requires:
+    - "api.rest"  # Needs HTTP framework
+
+technology:
+  runtime: "node"
+  language: "typescript"
+
+codeTemplates:
+  main:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/generic/main-generator.ts"
+    outputPattern: "{backendDir}/src/main.ts"
+
+  backendPackageJson:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/generic/backend-package-json-generator.ts"
+    outputPattern: "{backendDir}/package.json"
+
+  backendTsconfig:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/generic/backend-tsconfig-generator.ts"
+    outputPattern: "{backendDir}/tsconfig.json"
+
+  backendEnv:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/generic/backend-env-generator.ts"
+    outputPattern: "{backendDir}/.env"
+
+configuration:
+  outputStructure: "monorepo"
+  backendDir: "backend"
+
+  defaultPort: 3000
+  defaultHost: "0.0.0.0"

package/dist/libs/instance-factories/applications/react-app-runtime.yaml

@@ -0,0 +1,139 @@
+name: ReactAppRuntime
+version: "1.0.0"
+category: view
+description: "Slim React frontend using @specverse/runtime — dev views rendered at runtime, not generated"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [react, vite, spa, frontend, runtime]
+  mode: runtime
+
+compatibility:
+  specverse: ">=4.0.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "app.frontend"
+    - "ui.scaffolding"
+    - "ui.router"
+    - "ui.runtimeviews"
+  requires: []
+
+technology:
+  runtime: "browser"
+  language: "typescript"
+  framework: "react"
+  bundler: "vite"
+  router: "@specverse/runtime"
+  version: "^18.2.0"
+
+dependencies:
+  runtime:
+    - name: "react"
+      version: "^18.2.0"
+    - name: "react-dom"
+      version: "^18.2.0"
+    - name: "@tanstack/react-query"
+      version: "^5.0.0"
+    - name: "@specverse/runtime"
+      version: "^4.1.0"
+
+  dev:
+    - name: "@types/react"
+      version: "^18.2.0"
+    - name: "@types/react-dom"
+      version: "^18.2.0"
+    - name: "typescript"
+      version: "^5.2.0"
+    - name: "vite"
+      version: "^5.0.0"
+    - name: "@vitejs/plugin-react"
+      version: "^4.2.0"
+
+codeTemplates:
+  # === Infrastructure (same as static) ===
+  index-html:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/index-html-generator.ts"
+    outputPattern: "{frontendDir}/index.html"
+
+  main-tsx:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/main-tsx-generator.ts"
+    outputPattern: "{frontendDir}/src/main.tsx"
+
+  vite-config:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/vite-config-generator.ts"
+    outputPattern: "{frontendDir}/vite.config.ts"
+
+  tsconfig:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/tsconfig-generator.ts"
+    outputPattern: "{frontendDir}/tsconfig.json"
+
+  package-json:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/runtime-package-json-generator.ts"
+    outputPattern: "{frontendDir}/package.json"
+
+  index-css:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/index-css-generator.ts"
+    outputPattern: "{frontendDir}/src/index.css"
+
+  gitignore:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/gitignore-generator.ts"
+    outputPattern: "{frontendDir}/.gitignore"
+
+  env-example:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/env-example-generator.ts"
+    outputPattern: "{frontendDir}/.env.example"
+
+  # === Instance-specific wiring (still generated per project) ===
+  api-client:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/api-client-generator.ts"
+    outputPattern: "{frontendDir}/src/lib/apiClient.ts"
+
+  use-api-hooks:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/use-api-hooks-generator.ts"
+    outputPattern: "{frontendDir}/src/hooks/useApi.ts"
+
+  api-types:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/api-types-generator.ts"
+    outputPattern: "{frontendDir}/src/types/api.ts"
+
+  # === Runtime App (NEW — imports from @specverse/runtime) ===
+  app-tsx:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/runtime-app-tsx-generator.ts"
+    outputPattern: "{frontendDir}/src/App.tsx"
+
+  # === Removed from runtime mode (now in @specverse/runtime) ===
+  # view-form — FormView from @specverse/runtime
+  # view-list — RuntimeView from @specverse/runtime
+  # view-detail — RuntimeView from @specverse/runtime
+  # view-dashboard — RuntimeView from @specverse/runtime
+  # view-router — ViewRouter from @specverse/runtime
+  # pattern-adapter — ReactPatternAdapter from @specverse/runtime
+  # tailwind-adapter — TailwindAdapter from @specverse/runtime
+  # field-helpers — fieldClassification from @specverse/runtime
+  # relationship-field — RelationshipField from @specverse/runtime
+
+configuration:
+  projectStructure: "monorepo"
+  frontendDir: "frontend"
+  backendDir: "backend"
+
+  vite:
+    port: 5173
+    host: "localhost"
+    proxy:
+      "/api": "http://localhost:3000"