@specverse/engines 4.1.30 → 4.2.1

package/dist/libs/instance-factories/scaffolding/generic-scaffold.yaml

@@ -0,0 +1,65 @@
+name: GenericScaffold
+version: "1.0.0"
+category: scaffolding
+description: "Generic project scaffolding that adapts to manifest choices"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [scaffolding, project-setup, generic]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "project.scaffold"
+    - "project.package.json"
+    - "project.tsconfig"
+    - "project.gitignore"
+    - "project.env"
+
+technology:
+  runtime: "node"
+  language: "typescript"
+
+codeTemplates:
+  packageJson:
+    engine: typescript
+    generator: "libs/instance-factories/scaffolding/templates/generic/package-json-generator.ts"
+    outputPattern: "package.json"
+
+  tsconfig:
+    engine: typescript
+    generator: "libs/instance-factories/scaffolding/templates/generic/tsconfig-generator.ts"
+    outputPattern: "tsconfig.json"
+
+  tsconfigReact:
+    engine: typescript
+    generator: "libs/instance-factories/scaffolding/templates/generic/tsconfig-react-generator.ts"
+    outputPattern: "tsconfig.react.json"
+
+  env:
+    engine: typescript
+    generator: "libs/instance-factories/scaffolding/templates/generic/env-generator.ts"
+    outputPattern: ".env"
+
+  envExample:
+    engine: typescript
+    generator: "libs/instance-factories/scaffolding/templates/generic/env-example-generator.ts"
+    outputPattern: ".env.example"
+
+  gitignore:
+    engine: typescript
+    generator: "libs/instance-factories/scaffolding/templates/generic/gitignore-generator.ts"
+    outputPattern: ".gitignore"
+
+  readme:
+    engine: typescript
+    generator: "libs/instance-factories/scaffolding/templates/generic/readme-generator.ts"
+    outputPattern: "README.md"
+
+configuration:
+  defaultNodeVersion: "18.0.0"
+  defaultLicense: "MIT"

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

@@ -0,0 +1,28 @@
+# SDKs Instance Factory
+
+Generates typed client SDKs for consuming REST APIs produced by a SpecVerse specification.
+
+## Definitions
+
+- **`python-sdk.yaml`** -- Python SDK with async support (aiohttp + Pydantic)
+- **`typescript-sdk.yaml`** -- TypeScript SDK with native fetch (zero runtime dependencies)
+
+## Generators
+
+- `templates/python/sdk-generator.ts` -- Wraps `generate-sdk-python.js` (1000+ lines). Produces a complete Python package: async client class, per-controller resource classes, Pydantic models, exception classes, `setup.py`, and `requirements.txt`.
+- `templates/typescript/sdk-generator.ts` -- Wraps `generate-sdk-typescript.js` (900+ lines). Produces a complete npm package: client class, resource classes, TypeScript interfaces, error classes, `package.json`, and `tsconfig.json`.
+
+## Capabilities
+
+| SDK | Provides | Requires |
+|---|---|---|
+| Python | `sdk.python`, `client.rest.async` | `api.rest`, `api.rest.crud` |
+| TypeScript | `sdk.typescript`, `client.rest` | `api.rest`, `api.rest.crud` |
+
+## Default Configuration
+
+Both SDKs include authentication support, automatic retries (3 attempts), and a 30s timeout. The Python SDK defaults to package name `specverse_client`; TypeScript defaults to `@specverse/sdk`.
+
+## Status
+
+Wrapper implementations. Both YAMLs note future TODOs to convert the monolithic JS generators into native TypeScript template generators.

package/dist/libs/instance-factories/sdks/python-sdk.yaml

@@ -0,0 +1,66 @@
+name: PythonSDK
+version: "1.0.0"
+category: view
+description: "Python SDK generator for consuming REST APIs with async support and type hints"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [python, sdk, client, rest-api, async]
+
+compatibility:
+  specverse: ">=3.3.0"
+  python: ">=3.8"
+
+capabilities:
+  provides:
+    - "sdk.python"
+    - "client.rest.async"
+  requires:
+    - "api.rest"
+    - "api.rest.crud"
+
+technology:
+  runtime: "python"
+  language: "python"
+  framework: "native"
+  httpClient: "aiohttp"
+
+dependencies:
+  runtime:
+    - name: "aiohttp"
+      version: "^3.9.0"
+    - name: "pydantic"
+      version: "^2.0.0"
+  dev:
+    - name: "mypy"
+      version: "^1.7.0"
+    - name: "pytest"
+      version: "^7.4.0"
+    - name: "pytest-asyncio"
+      version: "^0.21.0"
+
+codeTemplates:
+  sdk:
+    engine: typescript
+    generator: "libs/instance-factories/sdks/templates/python/sdk-generator.ts"
+    outputPattern: "sdk-python/"
+
+configuration:
+  packageName: "specverse_client"
+  packageVersion: "1.0.0"
+  includeAuth: true
+  includeRetry: true
+  includeAsync: true
+  timeout: 30000
+  retries: 3
+
+# NOTE: This implementation type wraps the existing generate-sdk-python.js script
+# TODO: Future enhancement - Convert generate-sdk-python.js to native TypeScript template generator
+#       The current script is 1000+ lines and generates a complete Python package structure.
+#       Converting to native templates would require breaking it into multiple template files:
+#       - client-generator.ts (main async client class)
+#       - resource-generator.ts (per-controller resource classes)
+#       - types-generator.ts (Pydantic models)
+#       - errors-generator.ts (exception classes)
+#       - package-generator.ts (setup.py, requirements.txt)

package/dist/libs/instance-factories/sdks/typescript-sdk.yaml

@@ -0,0 +1,59 @@
+name: TypeScriptSDK
+version: "1.0.0"
+category: view
+description: "TypeScript SDK generator for consuming REST APIs with full type safety"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [typescript, sdk, client, rest-api]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "sdk.typescript"
+    - "client.rest"
+  requires:
+    - "api.rest"
+    - "api.rest.crud"
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "native"
+  httpClient: "fetch"
+
+dependencies:
+  runtime: []
+  dev:
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  sdk:
+    engine: typescript
+    generator: "libs/instance-factories/sdks/templates/typescript/sdk-generator.ts"
+    outputPattern: "sdk-typescript/"
+
+configuration:
+  packageName: "@specverse/sdk"
+  packageVersion: "1.0.0"
+  includeAuth: true
+  includeRetry: true
+  timeout: 30000
+  retries: 3
+
+# NOTE: This implementation type wraps the existing generate-sdk-typescript.js script
+# TODO: Future enhancement - Convert generate-sdk-typescript.js to native TypeScript template generator
+#       The current script is 900+ lines and generates a complete SDK package structure.
+#       Converting to native templates would require breaking it into multiple template files:
+#       - client-generator.ts (main client class)
+#       - resource-generator.ts (per-controller resource classes)
+#       - types-generator.ts (TypeScript interfaces)
+#       - errors-generator.ts (error classes)
+#       - package-generator.ts (package.json, tsconfig.json)

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

@@ -0,0 +1,55 @@
+# Services Factory
+
+Business logic generation with CURED operations and L3 behavior support.
+
+## Definition
+
+| File | Description |
+|------|-------------|
+| `prisma-services.yaml` | Prisma-backed controllers and services with CRUD and event publishing |
+
+## Generated Output
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `controller-generator` | `backend/src/controllers/{model}Controller.ts` | Per-model CURED controllers (Create, Update, Read, Execute, Delete) |
+| `service-generator` | `backend/src/services/{service}.ts` | Abstract business logic services (not tied to single model) |
+| `behavior-generator` | (imported by above) | L3 behavior generation: preconditions, steps, postconditions, events |
+
+### Controller vs Service
+
+- **Controllers** are model-specific — one per model, managing CURED operations and
+  event pub/sub for that model.
+- **Services** are cross-cutting — they can interact with multiple models and
+  implement business workflows.
+
+### Behavior Generator (L3)
+
+The behavior generator produces method bodies from behavioral metadata:
+- **Preconditions** become guard checks (throw on violation)
+- **Steps** become ordered business logic
+- **Postconditions** become dev-mode assertions
+- **publishes/sideEffects** become event publishing calls
+- **transactional** wraps in `prisma.$transaction`
+
+This is the third generation layer: L1 (schema) and L2 (CRUD) are handled by
+the ORM and controller generators.
+
+## Technology
+
+- **ORM**: @prisma/client ^5.5.0
+- **Patterns**: CURED operations, event-driven, transactional
+
+## Capabilities
+
+| Provides | Requires |
+|----------|----------|
+| `service.controller` | `orm.client` |
+| `service.business` | |
+| `service.crud` | |
+
+## Configuration
+
+- `validation: true` — input validation enabled
+- `eventPublishing: true` — events emitted on state changes
+- `errorHandling: "throw"` — exceptions propagate to caller

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

@@ -0,0 +1,71 @@
+name: PrismaServices
+version: "1.0.0"
+category: service
+description: "Business logic services using Prisma client for data access"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [services, business-logic, prisma, controllers]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "service.controller"  # Model-specific business logic (controllers)
+    - "service.business"    # Abstract business logic (services)
+    - "service.crud"        # CRUD operations
+  requires:
+    - "orm.client"          # Needs Prisma client for data access
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  orm: "prisma"
+
+dependencies:
+  runtime:
+    - name: "@prisma/client"
+      version: "^5.5.0"
+
+  dev:
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  controllers:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/prisma/controller-generator.ts"
+    outputPattern: "{backendDir}/src/controllers/{model}Controller.ts"
+
+  services:
+    engine: typescript
+    generator: "libs/instance-factories/services/templates/prisma/service-generator.ts"
+    outputPattern: "{backendDir}/src/services/{service}.ts"
+
+configuration:
+  outputStructure: "monorepo"
+  backendDir: "backend"
+
+  validation: true
+  eventPublishing: true
+  errorHandling: "throw"
+
+# Requirements for generic scaffolding (runtime-agnostic structure)
+requirements:
+  # Package dependencies (Node.js/npm-specific)
+  dependencies:
+    npm:
+      dependencies:
+        "@prisma/client": "^5.5.0"
+      # Services don't add extra scripts, they use the ones from Prisma
+
+  # No environment variables needed
+  environment: []
+
+  # No special configuration needed
+  configuration: {}

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

@@ -0,0 +1,34 @@
+# Storage Instance Factory
+
+Generates database connection configuration and Docker Compose files for three storage backends.
+
+## Definitions
+
+- **`mongodb.yaml`** -- MongoDB 6 with sharding and replication support
+- **`postgresql.yaml`** -- PostgreSQL 15 with production-tuned settings
+- **`redis.yaml`** -- Redis 7 for caching and session management
+
+## Generators
+
+Each backend has two generators under `templates/{backend}/`:
+
+| Generator | Output Pattern | Purpose |
+|---|---|---|
+| `config-generator.ts` | `config/database.{instance}.ts` | Connection config with pool settings |
+| `docker-generator.ts` | `docker/{service}.{instance}.yml` | Docker Compose service definition |
+
+## Capabilities
+
+| Backend | Provides |
+|---|---|
+| MongoDB | `storage.database`, `storage.database.document`, `storage.database.nosql` |
+| PostgreSQL | `storage.database`, `storage.database.relational`, `storage.database.sql` |
+| Redis | `storage.cache`, `storage.cache.memory`, `storage.session` |
+
+## Default Configuration
+
+- **MongoDB**: Pool 2-10, replication off by default, daily backups at 2am (7-day retention)
+- **PostgreSQL**: Pool 2-10, 256MB shared buffers, 100 max connections, daily backups
+- **Redis**: 256MB max memory, LRU eviction, AOF persistence, hourly backups
+
+All backends use environment variables for credentials (`${DB_HOST}`, `${REDIS_PASSWORD}`, etc.).

package/dist/libs/instance-factories/storage/mongodb.yaml

@@ -0,0 +1,79 @@
+name: MongoDB6
+version: "1.0.0"
+category: storage
+description: "MongoDB 6 document database with sharding and replication support"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [mongodb, database, nosql, document]
+
+compatibility:
+  specverse: ">=3.3.0"
+  mongodb: ">=6.0"
+
+capabilities:
+  provides:
+    - "storage.database"
+    - "storage.database.document"
+    - "storage.database.nosql"
+    - "database.mongodb"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  database: "mongodb"
+  version: "6.x"
+
+dependencies:
+  runtime: []  # Database runs separately
+
+  dev:
+    - name: "mongodb"
+      version: "^6.3.0"
+      description: "MongoDB driver for Node.js"
+
+codeTemplates:
+  config:
+    engine: typescript
+    generator: "libs/instance-factories/storage/templates/mongodb/config-generator.ts"
+    outputPattern: "config/database.{instance}.ts"
+
+  docker:
+    engine: typescript
+    generator: "libs/instance-factories/storage/templates/mongodb/docker-generator.ts"
+    outputPattern: "docker/mongodb.{instance}.yml"
+
+configuration:
+  # Database connection
+  host: "${MONGO_HOST:-localhost}"
+  port: 27017
+  database: "${MONGO_DB}"
+  username: "${MONGO_USER}"
+  password: "${MONGO_PASSWORD}"
+  authSource: "admin"
+
+  # Connection options
+  options:
+    maxPoolSize: 10
+    minPoolSize: 2
+    serverSelectionTimeoutMS: 5000
+    socketTimeoutMS: 45000
+
+  # Replication
+  replication:
+    enabled: false
+    replSetName: "rs0"
+    replicas: 3
+
+  # Sharding
+  sharding:
+    enabled: false
+    shardKey: "_id"
+
+  # Backup
+  backup:
+    enabled: true
+    schedule: "0 2 * * *"  # Daily at 2am
+    retention: 7  # days

package/dist/libs/instance-factories/storage/postgresql.yaml

@@ -0,0 +1,75 @@
+name: PostgreSQL15
+version: "1.0.0"
+category: storage
+description: "PostgreSQL 15 database with optimized configuration for production"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [postgresql, database, sql, relational]
+
+compatibility:
+  specverse: ">=3.3.0"
+  postgresql: ">=15.0"
+
+capabilities:
+  provides:
+    - "storage.database"
+    - "storage.database.relational"
+    - "storage.database.sql"
+    - "database.postgresql"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  database: "postgresql"
+  version: "15.x"
+
+dependencies:
+  runtime: []  # Database runs separately
+
+  dev:
+    - name: "pg"
+      version: "^8.11.0"
+      description: "PostgreSQL client for Node.js"
+
+codeTemplates:
+  config:
+    engine: typescript
+    generator: "libs/instance-factories/storage/templates/postgresql/config-generator.ts"
+    outputPattern: "config/database.{instance}.ts"
+
+  docker:
+    engine: typescript
+    generator: "libs/instance-factories/storage/templates/postgresql/docker-generator.ts"
+    outputPattern: "docker/postgres.{instance}.yml"
+
+configuration:
+  # Database connection
+  host: "${DB_HOST:-localhost}"
+  port: 5432
+  database: "${DB_NAME}"
+  username: "${DB_USER}"
+  password: "${DB_PASSWORD}"
+
+  # Connection pool
+  pool:
+    min: 2
+    max: 10
+    idleTimeoutMillis: 30000
+    connectionTimeoutMillis: 2000
+
+  # Performance
+  settings:
+    max_connections: 100
+    shared_buffers: "256MB"
+    effective_cache_size: "1GB"
+    work_mem: "16MB"
+    maintenance_work_mem: "128MB"
+
+  # Backup
+  backup:
+    enabled: true
+    schedule: "0 2 * * *"  # Daily at 2am
+    retention: 7  # days

package/dist/libs/instance-factories/storage/redis.yaml

@@ -0,0 +1,79 @@
+name: Redis7
+version: "1.0.0"
+category: storage
+description: "Redis 7 in-memory data store for caching and session management"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [redis, cache, session, key-value]
+
+compatibility:
+  specverse: ">=3.3.0"
+  redis: ">=7.0"
+
+capabilities:
+  provides:
+    - "storage.cache"
+    - "storage.cache.memory"
+    - "storage.session"
+    - "database.redis"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  database: "redis"
+  version: "7.x"
+
+dependencies:
+  runtime: []  # Database runs separately
+
+  dev:
+    - name: "redis"
+      version: "^4.6.0"
+      description: "Redis client for Node.js"
+    - name: "@types/redis"
+      version: "^4.0.11"
+
+codeTemplates:
+  config:
+    engine: typescript
+    generator: "libs/instance-factories/storage/templates/redis/config-generator.ts"
+    outputPattern: "config/cache.{instance}.ts"
+
+  docker:
+    engine: typescript
+    generator: "libs/instance-factories/storage/templates/redis/docker-generator.ts"
+    outputPattern: "docker/redis.{instance}.yml"
+
+configuration:
+  # Connection
+  host: "${REDIS_HOST:-localhost}"
+  port: 6379
+  password: "${REDIS_PASSWORD}"
+  database: 0
+
+  # Connection options
+  options:
+    connectTimeout: 10000
+    commandTimeout: 5000
+    retryStrategy: "exponential"
+    maxRetriesPerRequest: 3
+
+  # Memory management
+  memory:
+    maxMemory: "256mb"
+    evictionPolicy: "allkeys-lru"
+
+  # Persistence
+  persistence:
+    enabled: true
+    strategy: "aof"  # append-only file
+    fsync: "everysec"
+
+  # Backup
+  backup:
+    enabled: true
+    schedule: "0 * * * *"  # Hourly
+    retention: 24  # hours

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

@@ -0,0 +1,40 @@
+# Testing Instance Factory
+
+Generates a comprehensive Vitest test suite from a SpecVerse specification, covering unit, integration, and end-to-end tests.
+
+## Definition
+
+- **`vitest-tests.yaml`** -- Single definition for the full test suite (category: `service`).
+
+## Generator
+
+- `templates/vitest/tests-generator.ts` -- Wraps `generate-tests.js` (700+ lines). Produces a complete test directory structure.
+
+## Capabilities
+
+| Capability | Description |
+|---|---|
+| `testing.unit` | Service-layer unit tests |
+| `testing.integration` | Route integration tests |
+| `testing.e2e` | End-to-end workflow tests |
+
+## What Gets Generated
+
+- Unit tests for each service
+- Integration tests for each route
+- End-to-end tests for cross-model workflows
+- Test data fixtures
+- Prisma and EventBus mocks
+- Database and server setup utilities
+
+## Default Configuration
+
+All five generation flags are enabled by default: `generateUnitTests`, `generateIntegrationTests`, `generateE2ETests`, `generateFixtures`, `generateMocks`.
+
+## Dependencies
+
+Vitest 1.x with `@vitest/ui` for interactive test reporting.
+
+## Status
+
+Wrapper implementation. Future TODO to split into dedicated generators per test tier (unit, integration, e2e, fixtures, mocks, setup).