@specverse/engines 4.1.30 → 4.2.1

package/dist/libs/instance-factories/communication/event-emitter.yaml

@@ -0,0 +1,60 @@
+name: EventEmitter
+version: "2.0.0"
+category: communication
+description: "Typed in-memory event bus with WebSocket bridge for real-time frontend updates"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [events, in-memory, pubsub, websocket, eventemitter, development]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "messaging.pubsub"
+    - "messaging.events"
+    - "messaging.inmemory"
+    - "messaging.websocket"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "eventemitter3"
+  version: "^5.0.0"
+
+dependencies:
+  runtime:
+    - name: "eventemitter3"
+      version: "^5.0.0"
+    - name: "@fastify/websocket"
+      version: "^11.0.0"
+
+  dev:
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  types:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/eventemitter/types-generator.ts"
+    outputPattern: "{backendDir}/src/events/event-types.ts"
+
+  bus:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/eventemitter/bus-generator.ts"
+    outputPattern: "{backendDir}/src/events/eventBus.ts"
+
+  websocket:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/eventemitter/websocket-bridge-generator.ts"
+    outputPattern: "{backendDir}/src/events/websocket-bridge.ts"
+
+configuration:
+  maxListeners: 100
+  captureRejections: true
+  errorHandling: "log"
+  websocket: true

package/dist/libs/instance-factories/communication/rabbitmq-events.yaml

@@ -0,0 +1,87 @@
+name: RabbitMQEvents
+version: "1.0.0"
+category: communication
+description: "RabbitMQ event bus for pub/sub messaging and event-driven architecture"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [rabbitmq, events, messaging, pubsub, amqp]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "messaging.pubsub"
+    - "messaging.events"
+    - "messaging.queue"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "amqplib"
+  version: "^0.10.3"
+
+dependencies:
+  runtime:
+    - name: "amqplib"
+      version: "^0.10.3"
+    - name: "uuid"
+      version: "^9.0.0"
+
+  dev:
+    - name: "@types/amqplib"
+      version: "^0.10.4"
+    - name: "@types/uuid"
+      version: "^9.0.0"
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  publisher:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/rabbitmq/publisher-generator.ts"
+    outputPattern: "src/events/publishers/{event}Publisher.ts"
+
+  subscriber:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/rabbitmq/subscriber-generator.ts"
+    outputPattern: "src/events/subscribers/{event}Subscriber.ts"
+
+  connection:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/rabbitmq/connection-generator.ts"
+    outputPattern: "src/events/connection.ts"
+
+configuration:
+  connection:
+    protocol: "amqp"
+    hostname: "localhost"
+    port: 5672
+    username: "guest"
+    password: "guest"
+    vhost: "/"
+    heartbeat: 60
+
+  exchange:
+    type: "topic"
+    durable: true
+    autoDelete: false
+
+  queue:
+    durable: true
+    exclusive: false
+    autoDelete: false
+
+  publishing:
+    persistent: true
+    mandatory: true
+    confirmSelect: true
+
+  consuming:
+    prefetch: 10
+    noAck: false
+    exclusive: false

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

@@ -0,0 +1,42 @@
+# Controllers Factory
+
+Fastify REST API route handlers and server bootstrap generation.
+
+## Definition
+
+| File | Description |
+|------|-------------|
+| `fastify.yaml` | Fastify v4 REST API server with CORS, Helmet, and rate limiting |
+
+## Generated Output
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `routes-generator` | `backend/src/routes/{controller}.ts` | Per-model route handler with CRUD endpoints |
+| `meta-routes-generator` | `backend/src/routes/MetaRoutes.ts` | Meta API for spec/view metadata (serves frontend) |
+| `server-generator` | `backend/src/server.ts` | Server bootstrap — registers all model routes |
+
+The routes generator reads each controller from the spec and creates Fastify route
+handlers. The server generator auto-imports and registers all model route files.
+Meta routes expose spec and view metadata for the view-renderer architecture.
+
+## Technology
+
+- **Framework**: Fastify ^4.24.0
+- **Middleware**: @fastify/cors, @fastify/helmet, @fastify/rate-limit
+- **Language**: TypeScript with tsx for development
+
+## Capabilities
+
+| Provides | Requires |
+|----------|----------|
+| `api.rest` | `storage.database` |
+| `api.rest.crud` | `validation.runtime` |
+| `api.websocket` | |
+
+## Configuration
+
+- Server: port 3000, host 0.0.0.0, trust proxy, structured logging
+- CORS: origin true, credentials true
+- Rate limit: 100 requests per minute
+- Scripts: `dev` (tsx watch), `start` (node dist)

package/dist/libs/instance-factories/controllers/fastify.yaml

@@ -0,0 +1,139 @@
+name: FastifyAPI
+version: "1.0.0"
+category: controller
+description: "Fastify REST API server with WebSocket support"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [fastify, rest-api, websocket, controller]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "api.rest"
+    - "api.rest.crud"
+    - "api.websocket"
+  requires:
+    - "storage.database"  # Needs a database for data persistence
+    - "validation.runtime"  # Needs validation schemas
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "fastify"
+  version: "^4.24.0"
+
+dependencies:
+  runtime:
+    - name: "fastify"
+      version: "^4.24.0"
+    - name: "@fastify/cors"
+      version: "^8.4.0"
+    - name: "@fastify/helmet"
+      version: "^11.1.0"
+    - name: "@fastify/rate-limit"
+      version: "^9.0.0"
+    # .env loading — main.ts calls `import 'dotenv/config'` first so
+    # PORT and other env vars populate before any module reads them.
+    # Mirrors vite's loadEnv on the frontend side, so `npm run
+    # dev:backend` honours the project's .env without a set -a dance.
+    - name: "dotenv"
+      version: "^16.4.0"
+
+  dev:
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+    - name: "tsx"
+      version: "^4.0.0"
+
+codeTemplates:
+  routes:
+    engine: typescript
+    generator: "libs/instance-factories/controllers/templates/fastify/routes-generator.ts"
+    outputPattern: "{backendDir}/src/routes/{controller}.ts"
+
+  serviceRoutes:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/fastify/service-routes-generator.ts"
+    outputPattern: "{backendDir}/src/routes/{service}Routes.ts"
+
+  meta:
+    engine: typescript
+    generator: "libs/instance-factories/controllers/templates/fastify/meta-routes-generator.ts"
+    outputPattern: "{backendDir}/src/routes/MetaRoutes.ts"
+
+  server:
+    engine: typescript
+    generator: "libs/instance-factories/controllers/templates/fastify/server-generator.ts"
+    outputPattern: "{backendDir}/src/server.ts"
+
+configuration:
+  outputStructure: "monorepo"
+  backendDir: "backend"
+
+  server:
+    port: 3000
+    host: "0.0.0.0"
+    trustProxy: true
+    requestIdLogLabel: "reqId"
+    logger:
+      level: "info"
+      prettyPrint: true
+
+  middleware:
+    cors:
+      origin: true
+      credentials: true
+    helmet:
+      enabled: true
+    rateLimit:
+      max: 100
+      timeWindow: "1 minute"
+
+# Requirements for generic scaffolding (runtime-agnostic structure)
+requirements:
+  # Package dependencies (Node.js/npm-specific)
+  dependencies:
+    npm:
+      dependencies:
+        "fastify": "^5.8.3"
+        "@fastify/cors": "^10.0.0"
+        "yaml": "^2.3.0"
+        "dotenv": "^16.4.0"
+      devDependencies:
+        "tsx": "^4.0.0"
+      scripts:
+        "dev": "tsx watch src/main.ts"
+        "start": "node dist/main.js"
+
+  # Environment variables (universal structure)
+  environment:
+    - name: "PORT"
+      description: "Server port"
+      example: "3000"
+      required: false
+      category: "Server"
+    - name: "HOST"
+      description: "Server host"
+      example: "0.0.0.0"
+      required: false
+      category: "Server"
+    - name: "LOG_LEVEL"
+      description: "Logging level (trace, debug, info, warn, error, fatal)"
+      example: "info"
+      required: false
+      category: "Server"
+
+  # Build/runtime configuration (TypeScript-specific)
+  configuration:
+    tsconfig:
+      compilerOptions:
+        target: "ES2022"
+        module: "ESNext"
+        moduleResolution: "node"

package/dist/libs/instance-factories/controllers/templates/fastify/server-generator.js

@@ -29,6 +29,27 @@ function generateFastifyServer(context) {
  * Generated from SpecVerse specification
  */
 
+// Load .env from the closest ancestor that has one. Walks up from
+// this file's directory so the backend picks up the project-root
+// .env whether it's running in the monorepo layout
+// (generated/code/backend/src/main.ts with .env at generated/code/)
+// or the standalone layout (generated/code/src/main.ts with .env at
+// generated/code/). dotenv's default cwd-based behaviour doesn't
+// handle the monorepo case because npm workspaces \`cd\`s into the
+// workspace before running the script.
+import { config as loadEnv } from 'dotenv';
+import { existsSync } from 'fs';
+import { resolve as resolvePath, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+{
+  let dir = dirname(fileURLToPath(import.meta.url));
+  while (dir !== '/' && dir !== dirname(dir)) {
+    const candidate = join(dir, '.env');
+    if (existsSync(candidate)) { loadEnv({ path: candidate }); break; }
+    dir = dirname(dir);
+  }
+}
+
 import Fastify from 'fastify';
 import cors from '@fastify/cors';
 import { PrismaClient } from '@prisma/client';
@@ -94,9 +115,9 @@ ${hasEvents ? `    // Register WebSocket bridge for real-time frontend events
     // fall back to 127.0.0.1 cleanly. Binding :: fixes both cases.
     await fastify.listen({ port, host: '::' });
     console.log(\`Server running at http://localhost:\${port}\`);
-    console.log(\`API endpoints: ${modelNames.map((n) => `/api/${n.toLowerCase()}s`).join(", ")}\`);
+    console.log(\`API endpoints: ${modelNames.map((n) => `/api/${pluralizeLower(n)}`).join(", ")}\`);
 ${hasEvents ? `    console.log(\`WebSocket: ws://localhost:\${port}/ws\`);
-    console.log(\`Events: ${specEvents.join(", ")}\`);` : ""}
+    console.log(\`Events: ${specEvents.length} wired (GET /api/runtime/events for the full list)\`);` : ""}
   } catch (err) {
     fastify.log.error(err);
     process.exit(1);
@@ -106,6 +127,12 @@ ${hasEvents ? `    console.log(\`WebSocket: ws://localhost:\${port}/ws\`);
 start();
 `;
 }
+function pluralizeLower(s) {
+  const lower = s.toLowerCase();
+  if (/[^aeiou]y$/.test(lower)) return lower.slice(0, -1) + "ies";
+  if (/(s|x|z|ch|sh)$/.test(lower)) return lower + "es";
+  return lower + "s";
+}
 export {
   generateFastifyServer as default
 };

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

@@ -0,0 +1,29 @@
+# Infrastructure Instance Factory
+
+Generates Docker, Kubernetes, and CI/CD pipeline configurations from a SpecVerse specification.
+
+## Definition
+
+- **`docker-k8s.yaml`** -- Single definition covering Docker, Kubernetes, and GitHub Actions CI/CD.
+
+## Generator
+
+- `templates/docker-k8s/infrastructure-generator.ts` -- Wrapper that delegates to the existing `generate-infrastructure.js` script (650+ lines). Produces multi-stage Dockerfiles, docker-compose files, K8s manifests (deployments, services, ingress), and CI/CD pipelines.
+
+## Capabilities
+
+| Capability | Description |
+|---|---|
+| `infrastructure.docker` | Multi-stage Dockerfiles (Node 20 Alpine) |
+| `infrastructure.kubernetes` | K8s deployments, services, ingress (3 replicas, resource limits) |
+| `infrastructure.cicd` | GitHub Actions pipelines (build on push, deploy on tag) |
+
+## Default Configuration
+
+- **Docker**: Multi-stage builds, `node:20-alpine` base image
+- **Kubernetes**: `default` namespace, 3 replicas, 100m-500m CPU, 128Mi-512Mi memory
+- **CI/CD**: GitHub Actions with build-on-push and deploy-on-tag
+
+## Status
+
+Wrapper implementation. The YAML notes a future TODO to break the monolithic JS script into native TypeScript template generators (Dockerfile, docker-compose, K8s manifests, CI/CD, env config).

package/dist/libs/instance-factories/infrastructure/docker-k8s.yaml

@@ -0,0 +1,61 @@
+name: DockerKubernetes
+version: "1.0.0"
+category: infrastructure
+description: "Docker and Kubernetes infrastructure generator with CI/CD pipelines"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [docker, kubernetes, infrastructure, ci-cd, devops]
+
+compatibility:
+  specverse: ">=3.3.0"
+
+capabilities:
+  provides:
+    - "infrastructure.docker"
+    - "infrastructure.kubernetes"
+    - "infrastructure.cicd"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  containerization: "docker"
+  orchestration: "kubernetes"
+  cicd: "github-actions"
+
+codeTemplates:
+  infrastructure:
+    engine: typescript
+    generator: "libs/instance-factories/infrastructure/templates/docker-k8s/infrastructure-generator.ts"
+    outputPattern: "infrastructure/"
+
+configuration:
+  docker:
+    multiStage: true
+    nodeVersion: "20-alpine"
+  kubernetes:
+    namespace: "default"
+    replicas: 3
+    resources:
+      requests:
+        cpu: "100m"
+        memory: "128Mi"
+      limits:
+        cpu: "500m"
+        memory: "512Mi"
+  cicd:
+    provider: "github-actions"
+    buildOnPush: true
+    deployOnTag: true
+
+# NOTE: This implementation type wraps the existing generate-infrastructure.js script
+# TODO: Future enhancement - Convert generate-infrastructure.js to native TypeScript template generator
+#       The current script is 650+ lines and generates complete infrastructure as code.
+#       Converting to native templates would require breaking it into multiple template files:
+#       - dockerfile-generator.ts (multi-stage Dockerfiles)
+#       - docker-compose-generator.ts (development and production compositions)
+#       - kubernetes-generator.ts (K8s manifests - deployments, services, ingress)
+#       - cicd-generator.ts (GitHub Actions / GitLab CI pipelines)
+#       - env-generator.ts (environment configuration templates)

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

@@ -0,0 +1,54 @@
+# ORMs Factory
+
+Prisma schema and service generation from spec models.
+
+## Definition
+
+| File | Description |
+|------|-------------|
+| `prisma.yaml` | Prisma ^5.5 ORM with schema generation and typed client |
+
+## Generated Output
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `schema-generator` | `backend/prisma/schema.prisma` | Full Prisma schema from spec models (tables, relations, enums) |
+| `services-generator` | (per-model service) | Prisma service classes with ORM integration |
+
+The schema generator reads all spec models, maps SpecVerse types to Prisma types,
+generates relation fields (1:1, 1:N, N:M), and produces a complete `schema.prisma`
+file. It uses the `pluralize` utility from `@specverse/types` for table naming.
+
+## Technology
+
+- **ORM**: Prisma ^5.5.0
+- **Client**: @prisma/client (auto-generated)
+- **Default provider**: PostgreSQL (configurable)
+
+## Capabilities
+
+| Provides | Requires |
+|----------|----------|
+| `orm.prisma` | `storage.database` |
+| `orm.schema` | |
+| `orm.client` | |
+| `database.migrations` | |
+
+## Configuration
+
+- Provider: `postgresql` (default, overridable)
+- Relation mode: `foreignKeys`
+- Log levels: query, error, warn
+
+## Scripts
+
+```
+db:generate  — prisma generate
+db:migrate   — prisma migrate dev
+db:push      — prisma db push
+db:studio    — prisma studio
+```
+
+## Environment
+
+Requires `DATABASE_URL` (e.g., `postgresql://user:password@localhost:5432/dbname`)

package/dist/libs/instance-factories/orms/prisma.yaml

@@ -0,0 +1,89 @@
+name: PrismaORM
+version: "1.0.0"
+category: service
+description: "Prisma ORM for type-safe database access with auto-generated client"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [prisma, orm, database, typescript]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "orm.prisma"
+    - "orm.schema"
+    - "orm.client"
+    - "database.migrations"
+  requires:
+    - "storage.database"  # Needs actual database instance
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  orm: "prisma"
+  version: "^5.5.0"
+
+dependencies:
+  runtime:
+    - name: "@prisma/client"
+      version: "^5.5.0"
+
+  dev:
+    - name: "prisma"
+      version: "^5.5.0"
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  schema:
+    engine: typescript
+    generator: "libs/instance-factories/orms/templates/prisma/schema-generator.ts"
+    outputPattern: "{backendDir}/prisma/schema.prisma"
+
+configuration:
+  outputStructure: "monorepo"
+  backendDir: "backend"
+
+  provider: "postgresql"  # Default, can be overridden
+  relationMode: "foreignKeys"
+  log: ["query", "error", "warn"]
+  previewFeatures: []
+
+# Requirements for generic scaffolding (runtime-agnostic structure)
+requirements:
+  # Package dependencies (Node.js/npm-specific)
+  dependencies:
+    npm:
+      dependencies:
+        "@prisma/client": "^5.5.0"
+      devDependencies:
+        "prisma": "^5.5.0"
+      scripts:
+        "db:generate": "prisma generate"
+        "db:migrate": "prisma migrate dev"
+        "db:push": "prisma db push"
+        "db:studio": "prisma studio"
+
+  # Environment variables (universal structure)
+  environment:
+    - name: "DATABASE_URL"
+      description: "Database connection string"
+      example: "postgresql://user:password@localhost:5432/dbname"
+      required: true
+      category: "Database"
+
+  # Build/runtime configuration (TypeScript-specific)
+  configuration: {}
+
+  # Generated files
+  files:
+    - path: ".env"
+      description: "Environment variables"
+    - path: "prisma/schema.prisma"
+      description: "Prisma schema definition"

package/dist/libs/instance-factories/orms/templates/prisma/schema-generator.js

@@ -83,7 +83,7 @@ function buildMissingBackRefs(allModels, relationMap) {
           (r) => r.target === target && (r.type === "hasMany" || r.type === "hasOne")
         );
         const needsFieldInFk = parentRelsToSameTarget.length > 1;
-        const fkSuffix = needsFieldInFk ? camelToSnake(fieldName) + "_id" : camelToSnake(model.name.charAt(0).toLowerCase() + model.name.slice(1)) + "_id";
+        const fkSuffix = needsFieldInFk ? fieldName + "Id" : model.name.charAt(0).toLowerCase() + model.name.slice(1) + "Id";
         const fkName = fkSuffix;
         const fkPadding = " ".repeat(Math.max(1, 15 - fkName.length));
         const refFieldName = needsFieldInFk ? fieldName + model.name : model.name.charAt(0).toLowerCase() + model.name.slice(1);
@@ -270,7 +270,7 @@ function generateRelationship(rel, model, relationMap, hasOneTargets, allModels)
   const relAnnotation = ` @relation("${relName}")`;
   switch (rel.type) {
     case "belongsTo":
-      const fkBase = rel.foreignKey || camelToSnake(name) + "_id";
+      const fkBase = rel.foreignKey || name + "Id";
       const fkPadding = " ".repeat(Math.max(1, 15 - fkBase.length));
       const isUniqueFK = hasOneTargets.has(`${rel.target}->${model.name}`);
       let fkType = "String";

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

@@ -0,0 +1,49 @@
+# Scaffolding Factory
+
+Project-level configuration files that adapt to manifest choices.
+
+## Definition
+
+| File | Description |
+|------|-------------|
+| `generic-scaffold.yaml` | Generic project scaffolding — aggregates requirements from all factories |
+
+## Generated Output
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `package-json-generator` | `package.json` | Root package.json aggregating deps from all implementation types |
+| `tsconfig-generator` | `tsconfig.json` | TypeScript configuration |
+| `tsconfig-react-generator` | `tsconfig.react.json` | React-specific TypeScript config |
+| `env-generator` | `.env` | Environment variables with values |
+| `env-example-generator` | `.env.example` | Environment variable template (safe to commit) |
+| `gitignore-generator` | `.gitignore` | Git ignore rules |
+| `readme-generator` | `README.md` | Project README with tech stack and setup instructions |
+
+The package.json generator is the key file — it walks all instance factories in
+the manifest, aggregates their `requirements.dependencies` sections, and merges
+them into a single `package.json` with combined scripts, dependencies, and
+devDependencies.
+
+## Technology
+
+- **Runtime**: Node.js ^18.0.0
+- **Language**: TypeScript
+- **License**: MIT (default)
+
+## Capabilities
+
+| Provides | Requires |
+|----------|----------|
+| `project.scaffold` | (none) |
+| `project.package.json` | |
+| `project.tsconfig` | |
+| `project.gitignore` | |
+| `project.env` | |
+
+## How It Works
+
+Unlike other factories that generate domain-specific code, the scaffolding factory
+generates project infrastructure. It reads the full manifest to understand which
+other factories are in use, then aggregates their requirements into unified
+project files.