@specverse/engines 4.1.0

package/libs/instance-factories/sdks/templates/python/sdk-generator.ts

@@ -0,0 +1,50 @@
+/**
+ * Python SDK Generator Wrapper
+ *
+ * Wraps the existing generate-sdk-python.js script for use with the
+ * implementation types system.
+ *
+ * NOTE: This is a wrapper around scripts/generate-sdk-python.js
+ * TODO: Convert generate-sdk-python.js to native TypeScript template generator
+ *       See python-sdk.yaml for conversion notes.
+ */
+
+import type { TemplateContext } from '@specverse/types';
+import { generatePythonSDK } from '../../../../../scripts/generate-sdk-python.js';
+
+/**
+ * Generate Python SDK by delegating to the existing generator
+ */
+export default function generateSDK(context: TemplateContext): string {
+  const { spec, implType, outputDir } = context;
+
+  if (!spec) {
+    throw new Error('Specification is required in template context');
+  }
+
+  // Extract configuration from implementation type
+  const config = implType.configuration || {};
+
+  const options = {
+    packageName: config.packageName || 'specverse_client',
+    packageVersion: config.packageVersion || '1.0.0',
+    includeAuth: config.includeAuth !== false,
+    includeRetry: config.includeRetry !== false,
+    includeAsync: config.includeAsync !== false,
+    timeout: config.timeout || 30000,
+    retries: config.retries || 3
+  };
+
+  // Call the existing generator
+  const result = generatePythonSDK(spec, outputDir || './sdk-python', options);
+
+  // Return summary information
+  return JSON.stringify({
+    message: 'Python SDK generated successfully',
+    packageName: result.packageName,
+    resourceCount: result.resourceCount,
+    endpointCount: result.endpointCount,
+    outputDir: result.outputDir,
+    files: result.files
+  }, null, 2);
+}

package/libs/instance-factories/sdks/templates/typescript/sdk-generator.ts

@@ -0,0 +1,49 @@
+/**
+ * TypeScript SDK Generator Wrapper
+ *
+ * Wraps the existing generate-sdk-typescript.js script for use with the
+ * implementation types system.
+ *
+ * NOTE: This is a wrapper around scripts/generate-sdk-typescript.js
+ * TODO: Convert generate-sdk-typescript.js to native TypeScript template generator
+ *       See typescript-sdk.yaml for conversion notes.
+ */
+
+import type { TemplateContext } from '@specverse/types';
+import { generateTypeScriptSDK } from '../../../../../scripts/generate-sdk-typescript.js';
+
+/**
+ * Generate TypeScript SDK by delegating to the existing generator
+ */
+export default function generateSDK(context: TemplateContext): string {
+  const { spec, implType, outputDir } = context;
+
+  if (!spec) {
+    throw new Error('Specification is required in template context');
+  }
+
+  // Extract configuration from implementation type
+  const config = implType.configuration || {};
+
+  const options = {
+    packageName: config.packageName || '@specverse/sdk',
+    packageVersion: config.packageVersion || '1.0.0',
+    includeAuth: config.includeAuth !== false,
+    includeRetry: config.includeRetry !== false,
+    timeout: config.timeout || 30000,
+    retries: config.retries || 3
+  };
+
+  // Call the existing generator
+  const result = generateTypeScriptSDK(spec, outputDir || './sdk-typescript', options);
+
+  // Return summary information
+  return JSON.stringify({
+    message: 'TypeScript SDK generated successfully',
+    packageName: result.packageName,
+    resourceCount: result.resourceCount,
+    endpointCount: result.endpointCount,
+    outputDir: result.outputDir,
+    files: result.files
+  }, null, 2);
+}

package/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/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/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/libs/instance-factories/services/templates/memory/generate-interpreter.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env npx tsx
+/**
+ * Generate the behavior interpreter module for app-demo.
+ *
+ * Usage:
+ *   npx tsx generate-interpreter.ts -o ../../specverse-app-demo/src/runtime/engine/generated-behaviors.ts
+ *   npx tsx generate-interpreter.ts  (outputs to stdout)
+ */
+
+import { generateInterpreterModule } from './step-conventions-memory.js';
+
+const args = process.argv.slice(2);
+const outputIdx = args.indexOf('-o');
+
+const source = generateInterpreterModule();
+
+if (outputIdx !== -1 && args[outputIdx + 1]) {
+  const { writeFileSync } = await import('fs');
+  const { resolve } = await import('path');
+  const outPath = resolve(args[outputIdx + 1]);
+  writeFileSync(outPath, source, 'utf8');
+  console.log(`Generated ${outPath} (${source.split('\n').length} lines)`);
+} else {
+  console.log(source);
+}