@specverse/engines 4.1.0

package/libs/instance-factories/test-generation.ts

@@ -0,0 +1,192 @@
+/**
+ * Test v3.3 Implementation Types System
+ *
+ * Tests the complete flow from spec to generated code
+ */
+
+import { createDefaultLibrary, createResolver, createCodeGenerator, loadManifest } from '@specverse/engines/realize';
+import { UnifiedSpecVerseParser } from '@specverse/engine-parser';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+async function testV33Generation() {
+  console.log('🧪 Testing v3.3 Implementation Types System\n');
+
+  try {
+    // 1. Load Implementation Type Library
+    console.log('📚 Step 1: Loading Implementation Type Library...');
+    const library = await createDefaultLibrary(process.cwd());
+    const allTypes = library.find({});
+    console.log(`   ✅ Library loaded with ${allTypes.length} implementation types`);
+
+    // List loaded types
+    allTypes.forEach(type => {
+      console.log(`   - ${type.name} v${type.version} (${type.type})`);
+    });
+    console.log();
+
+    // 2. Load Manifest
+    console.log('📄 Step 2: Loading v3.3 Manifest...');
+    const manifestPath = resolve(process.cwd(), 'examples/v33-test/fastify-prisma-manifest.yaml');
+    const manifest = loadManifest(manifestPath);
+    console.log(`   ✅ Manifest loaded: ${manifest.name}`);
+    console.log(`   - Version: ${manifest.version}`);
+    console.log(`   - Implementation Types: ${manifest.implementationTypes?.length || 0}`);
+    console.log(`   - Capability Mappings: ${Object.keys(manifest.capabilityMappings || {}).length}`);
+    console.log();
+
+    // 3. Create Resolver
+    console.log('🔍 Step 3: Creating Capability Resolver...');
+    const resolver = createResolver(library, manifest);
+    console.log(`   ✅ Resolver created`);
+    console.log();
+
+    // 4. Parse Spec
+    console.log('📝 Step 4: Parsing Test Spec...');
+    // Use a simple existing example for now
+    const specPath = resolve(process.cwd(), 'examples/01-fundamentals/01-01-basic-model.specly');
+    const specContent = readFileSync(specPath, 'utf8');
+
+    const schemaPath = resolve(process.cwd(), 'schema/SPECVERSE-SCHEMA.json');
+    const schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+
+    const parser = new UnifiedSpecVerseParser(schema);
+    const parseResult = parser.parse(specContent, 'specly');
+
+    if (parseResult.errors && parseResult.errors.length > 0) {
+      console.error('   ❌ Parse errors:');
+      parseResult.errors.forEach((err: any) => {
+        console.error(`      - ${err.message}`);
+      });
+      return;
+    }
+
+    console.log(`   ✅ Spec parsed successfully`);
+    console.log(`   - Component: ${parseResult.ast?.components ? Object.keys(parseResult.ast.components)[0] : 'unknown'}`);
+    console.log(`   - Models: ${parseResult.ast?.components?.[Object.keys(parseResult.ast.components)[0]]?.models?.length || 0}`);
+    console.log(`   - Controllers: ${parseResult.ast?.components?.[Object.keys(parseResult.ast.components)[0]]?.controllers?.length || 0}`);
+
+    // Mock a deployment for testing (since basic example doesn't have one)
+    const deployment = {
+      environment: 'development',
+      instances: {
+        'apiServer': {
+          name: 'Test API Server',
+          type: 'api-server',
+          advertises: ['api.rest', 'api.rest.crud'],
+          uses: ['storage.database']
+        },
+        'database': {
+          name: 'Test Database',
+          type: 'storage',
+          advertises: ['storage.database', 'storage.prisma'],
+          uses: []
+        }
+      }
+    };
+    console.log(`   - Mocked deployment for testing`);
+    console.log(`   - Instances: ${Object.keys(deployment.instances || {}).length}`);
+    console.log();
+
+    // 5. Test Resolution
+    console.log('🔗 Step 5: Testing Capability Resolution...');
+    const apiInstance = deployment.instances?.['apiServer'];
+    if (!apiInstance) {
+      console.error('   ❌ No api-server instance found');
+      return;
+    }
+
+    console.log(`   Testing instance: ${apiInstance.name}`);
+    console.log(`   Advertises: ${apiInstance.advertises?.join(', ')}`);
+
+    const resolved = resolver.resolveForInstance(apiInstance);
+    console.log(`   ✅ Resolved ${resolved.length} implementation type(s)`);
+
+    resolved.forEach(impl => {
+      console.log(`   - ${impl.implementationType.name}`);
+      console.log(`     Capability: ${impl.capability}`);
+      console.log(`     Templates: ${Object.keys(impl.implementationType.codeTemplates).join(', ')}`);
+    });
+    console.log();
+
+    // 6. Test Code Generation
+    console.log('⚙️  Step 6: Testing Code Generation...');
+    const codeGen = createCodeGenerator({ outputDir: '/tmp/v33-test' });
+
+    // Get component data
+    const componentName = Object.keys(parseResult.ast?.components || {})[0];
+    const component = parseResult.ast?.components?.[componentName];
+    const model = component?.models?.[0];
+
+    // Mock a controller if not present
+    const controller = component?.controllers?.[0] || {
+      name: `${model?.name}Controller`,
+      path: `/api/${model?.name?.toLowerCase()}`,
+      model: model?.name,
+      endpoints: [
+        { operation: 'create', method: 'POST', path: '/' },
+        { operation: 'retrieve', method: 'GET', path: '/:id' },
+        { operation: 'update', method: 'PUT', path: '/:id' },
+        { operation: 'delete', method: 'DELETE', path: '/:id' },
+        { operation: 'list', method: 'GET', path: '/' }
+      ]
+    };
+
+    if (!model) {
+      console.error('   ❌ No model found in spec');
+      return;
+    }
+
+    console.log(`   Generating code for model: ${model.name}`);
+
+    // Test each template
+    const impl = resolved[0];
+    const templates = ['routes', 'services', 'schema'];
+
+    for (const templateName of templates) {
+      try {
+        console.log(`   Testing ${templateName} template...`);
+
+        const output = await codeGen.generateFromTemplate(
+          impl,
+          templateName,
+          {
+            spec: parseResult.ast,
+            model,
+            controller,
+            models: [model]
+          },
+          { outputDir: '/tmp/v33-test' }
+        );
+
+        console.log(`   ✅ ${templateName}: ${output.filePath}`);
+        console.log(`      Code length: ${output.code.length} characters`);
+        console.log(`      First 100 chars: ${output.code.substring(0, 100)}...`);
+      } catch (error) {
+        console.error(`   ❌ ${templateName} failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    console.log();
+
+    // 7. Summary
+    console.log('✅ All tests completed!');
+    console.log('\n📊 Summary:');
+    console.log(`   - Library: ✅ Loaded`);
+    console.log(`   - Manifest: ✅ Loaded`);
+    console.log(`   - Spec: ✅ Parsed`);
+    console.log(`   - Resolution: ✅ Working`);
+    console.log(`   - Generation: ✅ Working`);
+    console.log('\n🎉 v3.3 Implementation Types System is operational!');
+
+  } catch (error) {
+    console.error('\n❌ Test failed:', error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.stack) {
+      console.error('\nStack trace:');
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run test
+testV33Generation();

package/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/libs/instance-factories/testing/templates/vitest/tests-generator.ts

@@ -0,0 +1,51 @@
+/**
+ * Vitest Test Suite Generator Wrapper
+ *
+ * Wraps the existing generate-tests.js script for use with the
+ * implementation types system.
+ *
+ * NOTE: This is a wrapper around scripts/generate-tests.js
+ * TODO: Convert generate-tests.js to native TypeScript template generator
+ *       See vitest-tests.yaml for conversion notes.
+ */
+
+import type { TemplateContext } from '@specverse/types';
+import { generateTests } from '../../../../../scripts/generate-tests.js';
+
+/**
+ * Generate test suite by delegating to the existing generator
+ */
+export default function generateTestSuite(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 = {
+    testFramework: config.testFramework || 'vitest',
+    generateUnitTests: config.generateUnitTests !== false,
+    generateIntegrationTests: config.generateIntegrationTests !== false,
+    generateE2ETests: config.generateE2ETests !== false,
+    generateFixtures: config.generateFixtures !== false,
+    generateMocks: config.generateMocks !== false
+  };
+
+  // Call the existing generator
+  const result = generateTests(spec, outputDir || './tests', options);
+
+  // Return summary information
+  return JSON.stringify({
+    message: 'Test suite generated successfully',
+    unitTests: result.unitTests,
+    integrationTests: result.integrationTests,
+    e2eTests: result.e2eTests,
+    fixtureCount: result.fixtureCount,
+    mockCount: result.mockCount,
+    outputDir: result.outputDir,
+    files: result.files
+  }, null, 2);
+}

package/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/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/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/"

package/libs/instance-factories/tools/templates/mcp/mcp-server-generator.ts

@@ -0,0 +1,190 @@
+/**
+ * MCP Server Generator
+ *
+ * Generates a Model Context Protocol server from the SpecVerse spec.
+ * Ships the core server framework as static assets, generates tool/resource
+ * registration from the spec's ToolsSupport and CLI components.
+ */
+
+import type { TemplateContext } from '@specverse/types';
+import { existsSync, mkdirSync, writeFileSync, readdirSync, statSync, copyFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __generatorDir = dirname(fileURLToPath(import.meta.url));
+
+export default function generateMCPServer(context: TemplateContext): string {
+  const { spec, outputDir } = context;
+
+  const mcpDir = join(outputDir || '.', 'tools', 'specverse-mcp');
+  if (!existsSync(mcpDir)) mkdirSync(mcpDir, { recursive: true });
+
+  // 1. Copy static MCP server framework
+  // Check both source location (libs/) and compiled location (dist/libs/)
+  let staticDir = join(__generatorDir, 'static');
+  if (!existsSync(staticDir)) {
+    // Compiled JS is in dist/libs/ — static assets are in libs/
+    staticDir = __generatorDir.replace('/dist/libs/', '/libs/');
+    staticDir = join(staticDir, 'static');
+  }
+  if (existsSync(staticDir)) {
+    copyRecursive(staticDir, mcpDir);
+  } else {
+    console.warn(`[MCP Generator] Static assets not found at ${staticDir}`);
+  }
+
+  // 2. Generate tool registry from spec
+  const tools = extractMCPTools(spec);
+  const resources = extractMCPResources(spec);
+  const cliCommands = extractCLICommands(spec);
+
+  // 3. Generate a spec-driven registration file
+  const registryCode = generateToolRegistry(tools, resources, cliCommands);
+  const registryDir = join(mcpDir, 'src', 'generated');
+  if (!existsSync(registryDir)) mkdirSync(registryDir, { recursive: true });
+  writeFileSync(join(registryDir, 'spec-registry.ts'), registryCode);
+
+  return `MCP server generated in: ${mcpDir}\n  ${tools.length} tools, ${resources.length} resources, ${cliCommands.length} CLI commands`;
+}
+
+function extractMCPTools(spec: any): Array<{ name: string; description: string; isEntityTool: boolean }> {
+  const tools: Array<{ name: string; description: string; isEntityTool: boolean }> = [];
+  const components = spec?.components || {};
+  const componentList = Array.isArray(components) ? components : Object.values(components);
+
+  // Also check top-level services (AI-optimized spec format)
+  if (spec?.services && !Array.isArray(components)) {
+    componentList.push({ services: spec.services, models: spec.models } as any);
+  }
+
+  for (const component of componentList) {
+    const comp = component as any;
+
+    // Extract from services — each service operation becomes an MCP tool
+    const services = comp?.services;
+    if (services) {
+      const serviceList = Array.isArray(services) ? services : Object.entries(services).map(([n, d]) => ({ name: n, ...(d as any) }));
+      for (const service of serviceList) {
+        const operations = service.operations;
+        if (operations) {
+          const opEntries = Array.isArray(operations)
+            ? operations
+            : Object.entries(operations).map(([n, d]) => ({ name: n, ...(d as any) }));
+          for (const op of opEntries) {
+            tools.push({
+              name: `${service.name.replace(/Service$/, '').toLowerCase()}-${op.name}`,
+              description: op.description || `${op.name} via ${service.name}`,
+              isEntityTool: false,
+            });
+          }
+        }
+      }
+    }
+
+    // Extract from model behaviors — each behavior becomes an MCP tool
+    const models = comp?.models;
+    if (models) {
+      const modelList = Array.isArray(models) ? models : Object.entries(models).map(([n, d]) => ({ name: n, ...(d as any) }));
+      for (const model of modelList) {
+        const behaviors = model.behaviors;
+        if (behaviors) {
+          const behaviorEntries = typeof behaviors === 'object' && !Array.isArray(behaviors)
+            ? Object.entries(behaviors).map(([n, d]) => ({ name: n, ...(d as any) }))
+            : [];
+          for (const behavior of behaviorEntries) {
+            tools.push({
+              name: `${model.name.toLowerCase()}-${behavior.name}`,
+              description: behavior.description || `${behavior.name} on ${model.name}`,
+              isEntityTool: true,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // Also extract from CLI commands
+  const cliCmds = extractCLICommands(spec);
+  for (const cmd of cliCmds) {
+    tools.push({
+      name: `specverse-${cmd}`,
+      description: `Execute specverse ${cmd} command`,
+      isEntityTool: false,
+    });
+  }
+
+  // Default fallback
+  if (tools.length === 0) {
+    tools.push(
+      { name: 'specverse-validate', description: 'Validate a specification', isEntityTool: false },
+      { name: 'specverse-create', description: 'Create a specification', isEntityTool: false },
+    );
+  }
+  return tools;
+}
+
+function extractMCPResources(spec: any): Array<{ uri: string; name: string; description: string }> {
+  return [
+    { uri: 'specverse://schema', name: 'SpecVerse Schema', description: 'JSON Schema for .specly validation' },
+    { uri: 'specverse://conventions', name: 'Convention Reference', description: 'Convention syntax patterns' },
+    { uri: 'specverse://library-catalog', name: 'Library Catalog', description: 'Available SpecVerse libraries' },
+    { uri: 'specverse://prompts', name: 'Prompt Templates', description: 'AI prompt template versions' },
+  ];
+}
+
+function extractCLICommands(spec: any): string[] {
+  const commands: string[] = [];
+  const components = spec?.components || [];
+  for (const component of Array.isArray(components) ? components : Object.values(components)) {
+    const cliCommands = (component as any)?.commands;
+    if (!cliCommands) continue;
+    for (const [, rootDef] of Object.entries(cliCommands as Record<string, any>)) {
+      const subs = (rootDef as any)?.subcommands || {};
+      for (const subName of Object.keys(subs)) {
+        commands.push(subName);
+      }
+    }
+  }
+  return commands;
+}
+
+function generateToolRegistry(
+  tools: Array<{ name: string; description: string; isEntityTool: boolean }>,
+  resources: Array<{ uri: string; name: string; description: string }>,
+  cliCommands: string[]
+): string {
+  return `/**
+ * Spec-Driven MCP Registry
+ * Generated from SpecVerse self-specification.
+ *
+ * Tools, resources, and CLI command mappings derived from the spec.
+ */
+
+export const SPEC_TOOLS = ${JSON.stringify(tools, null, 2)};
+
+export const SPEC_RESOURCES = ${JSON.stringify(resources, null, 2)};
+
+export const CLI_COMMANDS = ${JSON.stringify(cliCommands, null, 2)};
+
+export function getToolByName(name: string) {
+  return SPEC_TOOLS.find(t => t.name === name);
+}
+
+export function getResourceByUri(uri: string) {
+  return SPEC_RESOURCES.find(r => r.uri === uri);
+}
+`;
+}
+
+function copyRecursive(src: string, dest: string) {
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      if (!existsSync(destPath)) mkdirSync(destPath, { recursive: true });
+      copyRecursive(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}