@specverse/engines 4.2.0 → 4.2.2

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).

package/dist/libs/instance-factories/testing/vitest-tests.yaml

@@ -0,0 +1,63 @@
+name: VitestTests
+version: "1.0.0"
+category: service
+description: "Comprehensive test suite generator with Vitest - unit, integration, and e2e tests"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [vitest, testing, typescript, unit, integration, e2e]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "testing.unit"
+    - "testing.integration"
+    - "testing.e2e"
+  requires:
+    - "api.rest"
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  testFramework: "vitest"
+  testRunner: "vitest"
+
+dependencies:
+  dev:
+    - name: "vitest"
+      version: "^1.0.0"
+    - name: "@vitest/ui"
+      version: "^1.0.0"
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  tests:
+    engine: typescript
+    generator: "libs/instance-factories/testing/templates/vitest/tests-generator.ts"
+    outputPattern: "tests/"
+
+configuration:
+  testFramework: "vitest"
+  generateUnitTests: true
+  generateIntegrationTests: true
+  generateE2ETests: true
+  generateFixtures: true
+  generateMocks: true
+
+# NOTE: This implementation type wraps the existing generate-tests.js script
+# TODO: Future enhancement - Convert generate-tests.js to native TypeScript template generator
+#       The current script is 700+ lines and generates a complete test suite structure.
+#       Converting to native templates would require breaking it into multiple template files:
+#       - unit-tests-generator.ts (service layer unit tests)
+#       - integration-tests-generator.ts (route integration tests)
+#       - e2e-tests-generator.ts (end-to-end workflow tests)
+#       - fixtures-generator.ts (test data fixtures)
+#       - mocks-generator.ts (Prisma and EventBus mocks)
+#       - setup-generator.ts (database and server setup utilities)

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

@@ -0,0 +1,70 @@
+# Tools Instance Factory
+
+Generates two complete developer tool packages from a SpecVerse specification: an MCP (Model Context Protocol) server and a VSCode extension. Unlike most other instance factories, these are **not wrappers** -- they are native TypeScript generators that ship substantial static asset trees.
+
+## Generators
+
+### MCP Server (`templates/mcp/`)
+
+**`mcp-server-generator.ts`** generates a fully functional MCP server by:
+
+1. Copying the `static/` framework (a complete Node.js project with 9 service classes)
+2. Extracting tools, resources, and CLI commands from the spec
+3. Generating `src/generated/spec-registry.ts` with spec-driven tool/resource registration
+
+The static framework includes:
+
+- **Server**: `mcp-server.ts` -- StdioServerTransport-based MCP server with event handling
+- **Controller**: `MCPServerController.ts` -- Request routing and lifecycle management
+- **Services**: 9 service classes including `CLIProxyService`, `HybridResourcesProvider`, `OrchestratorBridge`, `LibraryToolsService`, `PromptToolsService`, `EntityModuleService`, and others
+- **Deployment targets**: Local (stdio), Web (HTTP), Extension (embedded), Enterprise (Docker)
+- **Build scripts**: Per-deployment builders (`build-local.js`, `build-web.js`, `build-extension.js`, `build-enterprise.js`)
+- **Tests**: Unit tests for `CLIProxyService` and `ResourcesProviderService`
+- **Docs**: Deployment guides (local, web, extension) and hybrid resource system documentation
+
+The generated MCP server exposes tools like `specverse-create`, `specverse-analyse`, `specverse-validate`, `specverse-realize`, and `specverse-suggest`, plus resources for schema, conventions, library catalog, and prompt templates.
+
+**Package**: `@specverse/mcp` v3.5.2, depends on `@modelcontextprotocol/sdk` and `@specverse/lang`.
+
+### VSCode Extension (`templates/vscode/`)
+
+**`vscode-extension-generator.ts`** generates a publishable VSCode extension by:
+
+1. Extracting CLI commands from the spec (with nested subcommand support)
+2. Extracting entity type keywords for syntax highlighting
+3. Generating `package.json` with commands, keybindings, and contributes
+4. Copying static assets and generating an esbuild script
+
+The static assets include:
+
+- **`extension.ts`** -- Extension activation and command registration
+- **`syntaxes/specverse.tmLanguage.json`** -- TextMate grammar for `.specly` files
+- **`themes/`** -- Four color theme variants (basic, complete, colors, complete-colors)
+- **`schemas/specverse-v3-schema.json`** -- JSON Schema for in-editor validation
+- **`language-configuration.json`** -- Bracket matching, auto-closing, comment toggling
+
+## Output Structure
+
+```
+tools/
+  specverse-mcp/          # Complete MCP server project
+    src/
+      controllers/
+      events/
+      interfaces/
+      models/
+      server/
+      services/
+      generated/          # <-- spec-driven registry (generated)
+    scripts/
+    docs/
+    package.json
+    tsconfig.json
+  vscode-extension/       # Complete VSCode extension project
+    src/extension.ts
+    syntaxes/
+    themes/
+    schemas/
+    scripts/build.js
+    package.json
+```

package/dist/libs/instance-factories/tools/mcp.yaml

@@ -0,0 +1,36 @@
+name: MCPServer
+version: "4.0.0"
+category: tools
+description: "MCP server exposing services as AI-accessible tools via the Model Context Protocol"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [mcp, ai, tools, claude, llm]
+
+compatibility:
+  specverse: "^4.0.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "tools.mcp"
+    - "tools.mcp.server"
+  requires:
+    - "service.controller"
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "@modelcontextprotocol/sdk"
+
+dependencies:
+  runtime:
+    - name: "@modelcontextprotocol/sdk"
+      version: "^1.0.0"
+
+codeTemplates:
+  mcp-server:
+    engine: typescript
+    generator: "libs/instance-factories/tools/templates/mcp/mcp-server-generator.ts"
+    outputPattern: "tools/specverse-mcp/"