@specverse/engines 4.2.0 → 4.2.2

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.

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)