@specverse/engine-realize 3.5.3

package/libs/instance-factories/tools/templates/mcp/static/src/services/EmbeddedResourcesAdapter.ts

@@ -0,0 +1,211 @@
+/**
+ * EmbeddedResourcesAdapter
+ * Handles embedded resources for web deployments
+ */
+
+import { SpecVerseResourceModel } from '../models/SpecVerseResource.js';
+import type { ResourceProvider } from '../interfaces/ResourceProvider.js';
+import type { SpecVerseResource, MCPToolResult } from '../types/index.js';
+
+export interface EmbeddedResourceData {
+  content: string;
+  mimeType: string;
+  size: number;
+}
+
+export interface EmbeddedResourcesMap {
+  [path: string]: EmbeddedResourceData;
+}
+
+export class EmbeddedResourcesAdapter implements ResourceProvider {
+  private resourceCatalog: Map<string, SpecVerseResourceModel> = new Map();
+  private embeddedResources: EmbeddedResourcesMap;
+  private isInitialized = false;
+
+  constructor(embeddedResources: EmbeddedResourcesMap) {
+    this.embeddedResources = embeddedResources;
+  }
+
+  async initializeResources(): Promise<void> {
+    if (this.isInitialized) {
+      return;
+    }
+
+    // Initialize resource catalog with known resources using embedded content
+    const resources: SpecVerseResource[] = [
+      {
+        uri: 'specverse://schema/json',
+        name: 'SpecVerse v3.1 JSON Schema',
+        description: 'Complete JSON schema for SpecVerse v3.1 specifications',
+        mimeType: 'application/json'
+      },
+      {
+        uri: 'specverse://schema/ai-yaml',
+        name: 'SpecVerse v3.1 AI-Optimized Schema',
+        description: 'AI-friendly YAML schema with guidance and examples',
+        mimeType: 'application/x-yaml'
+      },
+      {
+        uri: 'specverse://prompts/create',
+        name: 'Create Prompt Template',
+        description: 'Template for generating SpecVerse specifications from requirements',
+        mimeType: 'application/x-yaml'
+      },
+      {
+        uri: 'specverse://prompts/analyse',
+        name: 'Analysis Prompt Template',
+        description: 'Template for extracting specifications from existing code',
+        mimeType: 'application/x-yaml'
+      },
+      {
+        uri: 'specverse://prompts/materialise',
+        name: 'Implementation Planning Template',
+        description: 'Template for creating implementation plans from specifications',
+        mimeType: 'application/x-yaml'
+      },
+      {
+        uri: 'specverse://prompts/realize',
+        name: 'Code Generation Template',
+        description: 'Template for generating source code from specifications',
+        mimeType: 'application/x-yaml'
+      },
+      {
+        uri: 'specverse://libraries/catalog',
+        name: 'SpecVerse Library Catalog',
+        description: 'Complete catalog of available SpecVerse libraries with AI metadata',
+        mimeType: 'application/x-yaml'
+      },
+      {
+        uri: 'specverse://examples/chat-prompts',
+        name: 'Chat Prompt Examples',
+        description: 'Example prompts for terminal/chat-based AI interactions',
+        mimeType: 'text/markdown'
+      },
+      {
+        uri: 'specverse://examples/api-calls',
+        name: 'API Integration Examples',
+        description: 'Examples for API-based AI integrations',
+        mimeType: 'application/javascript'
+      }
+    ];
+
+    for (const resourceData of resources) {
+      const resource = SpecVerseResourceModel.create(resourceData);
+      this.resourceCatalog.set(resource.uri, resource);
+    }
+
+    this.isInitialized = true;
+  }
+
+  async listResources(): Promise<SpecVerseResource[]> {
+    await this.initializeResources();
+    
+    return Array.from(this.resourceCatalog.values()).map(resource => ({
+      uri: resource.uri,
+      name: resource.name,
+      description: resource.description,
+      mimeType: resource.mimeType,
+      content: resource.content,
+      metadata: resource.metadata
+    }));
+  }
+
+  async getResourceContent(uri: string): Promise<string> {
+    await this.initializeResources();
+    
+    const resource = this.resourceCatalog.get(uri);
+    if (!resource) {
+      throw new Error(`Resource not found: ${uri}`);
+    }
+
+    if (resource.isLoaded()) {
+      return resource.content!;
+    }
+
+    // Load content from embedded resources
+    const resourcePath = this.resolveResourcePath(uri);
+    const embeddedResource = this.embeddedResources[resourcePath];
+    
+    if (!embeddedResource) {
+      throw new Error(`Embedded resource not found: ${resourcePath} for URI: ${uri}`);
+    }
+
+    // Update resource with loaded content
+    const updatedResource = resource.withContent(embeddedResource.content);
+    this.resourceCatalog.set(uri, updatedResource);
+    
+    return embeddedResource.content;
+  }
+
+  async readResource(uri: string): Promise<MCPToolResult> {
+    try {
+      const content = await this.getResourceContent(uri);
+      const resource = this.resourceCatalog.get(uri)!;
+      
+      return {
+        content: [{
+          type: 'resource',
+          resource: {
+            uri: resource.uri,
+            name: resource.name,
+            description: resource.description,
+            mimeType: resource.mimeType,
+            content
+          }
+        }]
+      };
+    } catch (error) {
+      return {
+        content: [{
+          type: 'text',
+          text: `Error reading resource: ${error instanceof Error ? error.message : String(error)}`
+        }],
+        isError: true
+      };
+    }
+  }
+
+  private resolveResourcePath(uri: string): string {
+    switch (uri) {
+      case 'specverse://schema/json':
+        return 'schemas/SPECVERSE-SCHEMA.json';
+      case 'specverse://schema/ai-yaml':
+        return 'schemas/specverse-ai.yaml';
+      case 'specverse://prompts/create':
+        return 'prompts/create.prompt.yaml';
+      case 'specverse://prompts/analyse':
+        return 'prompts/analyse.prompt.yaml';
+      case 'specverse://prompts/materialise':
+        return 'prompts/materialise.prompt.yaml';
+      case 'specverse://prompts/realize':
+        return 'prompts/realize.prompt.yaml';
+      case 'specverse://libraries/catalog':
+        return 'libraries/catalog/library-catalog.yaml';
+      case 'specverse://examples/chat-prompts':
+        return 'examples/chat-prompts/ecommerce-store-example.md';
+      case 'specverse://examples/api-calls':
+        return 'examples/api-calls/orchestrator-workflow-example.js';
+      default:
+        throw new Error(`Unknown resource URI: ${uri}`);
+    }
+  }
+
+  isResourceAvailable(uri: string): boolean {
+    return this.resourceCatalog.has(uri);
+  }
+
+  getCachedResourceCount(): number {
+    return Array.from(this.resourceCatalog.values()).filter(r => r.isLoaded()).length;
+  }
+
+  getEmbeddedResourcesInfo(): { count: number; totalSize: number; paths: string[] } {
+    const paths = Object.keys(this.embeddedResources);
+    const totalSize = Object.values(this.embeddedResources).reduce((sum, res) => sum + res.size, 0);
+    
+    return {
+      count: paths.length,
+      totalSize,
+      paths
+    };
+  }
+}

package/libs/instance-factories/tools/templates/mcp/static/src/services/EntityModuleService.ts

@@ -0,0 +1,308 @@
+/**
+ * EntityModuleService
+ *
+ * Provides entity module metadata as MCP resources and tools.
+ * Loads the entity registry from @specverse/engine-entities and exposes:
+ * - Entity module registry (all modules, their facets, dependencies)
+ * - Convention grammars per entity (what behavioural constraints are available)
+ * - Inference rules per entity (what gets generated from what)
+ * - Diagram plugins per entity
+ * - Behavioural constraint expansion (tool)
+ */
+
+import type { SpecVerseResource, MCPToolResult } from '../types/index.js';
+
+interface EntityModuleInfo {
+  name: string;
+  type: string;
+  version: string;
+  dependsOn: string[];
+  hasConventionProcessor: boolean;
+  inferenceRuleCount: number;
+  inferenceRules: Array<{ id: string; description: string; triggeredBy: string; generates?: string[] }>;
+  diagramPlugins: Array<{ type: string; variants?: string[] }>;
+  generatorCount: number;
+}
+
+interface ConventionInfo {
+  entity: string;
+  domain: string;
+  conventions: Array<{
+    name: string;
+    pattern: string;
+    description: string;
+    expandsTo: string;
+  }>;
+}
+
+export class EntityModuleService {
+  private registry: any = null;
+  private behaviouralProcessor: any = null;
+  private loaded = false;
+
+  /**
+   * Attempt to load the entity registry from @specverse/engine-entities.
+   * Fails gracefully if not available.
+   */
+  async initialize(): Promise<boolean> {
+    try {
+      // Dynamic imports — paths resolved at runtime, not compile time
+      // The MCP server sits in tools/specverse-mcp/ but needs to reach src/entities/
+      const { resolve, dirname } = await import('path');
+      const { fileURLToPath } = await import('url');
+      const baseDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+      const entitiesPath = resolve(baseDir, 'dist', 'entities', 'index.js');
+      const conventionPath = resolve(baseDir, 'dist', 'entities', '_shared', 'behaviour', 'convention-processor.js');
+
+      const entitiesModule = await import(entitiesPath);
+      entitiesModule.bootstrapEntityModules();
+      this.registry = entitiesModule.getEntityRegistry();
+
+      const { BehaviouralConventionProcessor } = await import(conventionPath);
+      this.behaviouralProcessor = new BehaviouralConventionProcessor();
+
+      // Load grammars from entity module source (grammar.yaml files)
+      const entitiesDir = resolve(baseDir, 'src', 'entities');
+      this.behaviouralProcessor.loadGrammarsFromEntities(entitiesDir);
+
+      this.loaded = true;
+      return true;
+    } catch (error) {
+      // Entity modules not available in this deployment context
+      this.loaded = false;
+      return false;
+    }
+  }
+
+  isAvailable(): boolean {
+    return this.loaded;
+  }
+
+  /**
+   * Get entity module metadata for all registered modules.
+   */
+  getEntityModules(): EntityModuleInfo[] {
+    if (!this.registry) return [];
+
+    const modules = this.registry.getInDependencyOrder();
+    return modules.map((mod: any) => ({
+      name: mod.name,
+      type: mod.type,
+      version: mod.version,
+      dependsOn: mod.dependsOn || [],
+      hasConventionProcessor: !!mod.conventionProcessor,
+      inferenceRuleCount: mod.inferenceRules?.length || 0,
+      inferenceRules: (mod.inferenceRules || []).map((r: any) => ({
+        id: r.id,
+        description: r.description,
+        triggeredBy: r.triggeredBy,
+        generates: r.generates,
+      })),
+      diagramPlugins: mod.diagramPlugins || [],
+      generatorCount: mod.generators?.length || 0,
+    }));
+  }
+
+  /**
+   * Get behavioural convention grammars for all entities.
+   */
+  getConventionGrammars(): ConventionInfo[] {
+    if (!this.behaviouralProcessor) return [];
+
+    return this.behaviouralProcessor.getGrammars().map((g: any) => ({
+      entity: g.entity,
+      domain: g.domain,
+      conventions: Object.values(g.conventions).map((c: any) => ({
+        name: c.name,
+        pattern: c.pattern,
+        description: c.description,
+        expandsTo: c.expandsTo,
+      })),
+    }));
+  }
+
+  /**
+   * Expand a behavioural constraint string.
+   */
+  expandConstraint(input: string): { success: boolean; result?: any; error?: string } {
+    if (!this.behaviouralProcessor) {
+      return { success: false, error: 'Behavioural convention processor not available' };
+    }
+
+    const result = this.behaviouralProcessor.expand(input);
+    if (result) {
+      return { success: true, result };
+    }
+    return { success: false, error: `No matching convention pattern for: "${input}"` };
+  }
+
+  /**
+   * Generate MCP resources from entity module metadata.
+   */
+  generateResources(): SpecVerseResource[] {
+    if (!this.loaded) return [];
+
+    const resources: SpecVerseResource[] = [];
+
+    // 1. Entity registry overview
+    const modules = this.getEntityModules();
+    resources.push({
+      uri: 'specverse://entities/registry',
+      name: 'Entity Module Registry',
+      description: `All ${modules.length} registered entity modules with their facets, dependencies, and capabilities`,
+      mimeType: 'application/json',
+      content: JSON.stringify({ entityModules: modules }, null, 2),
+    });
+
+    // 2. Behavioural conventions catalog
+    const grammars = this.getConventionGrammars();
+    const totalConventions = grammars.reduce((sum, g) => sum + g.conventions.length, 0);
+    resources.push({
+      uri: 'specverse://entities/conventions',
+      name: 'Behavioural Conventions Catalog',
+      description: `${totalConventions} behavioural conventions across ${grammars.length} entities. Use in constraints: section of .specly files.`,
+      mimeType: 'application/json',
+      content: JSON.stringify({ grammars }, null, 2),
+    });
+
+    // 3. Inference rules summary
+    const allRules = modules.flatMap(m => m.inferenceRules);
+    resources.push({
+      uri: 'specverse://entities/inference-rules',
+      name: 'Inference Rules Summary',
+      description: `${allRules.length} inference rules that generate architecture from specifications`,
+      mimeType: 'application/json',
+      content: JSON.stringify({ rules: allRules }, null, 2),
+    });
+
+    // 4. Diagram plugins summary
+    const allPlugins = modules.flatMap(m =>
+      m.diagramPlugins.map(p => ({ ...p, entity: m.name }))
+    );
+    resources.push({
+      uri: 'specverse://entities/diagram-plugins',
+      name: 'Diagram Plugins',
+      description: `${allPlugins.length} diagram types available for visualization`,
+      mimeType: 'application/json',
+      content: JSON.stringify({ plugins: allPlugins }, null, 2),
+    });
+
+    return resources;
+  }
+
+  /**
+   * Generate MCP tools for entity module interaction.
+   */
+  generateTools(): any[] {
+    if (!this.loaded) return [];
+
+    return [
+      {
+        name: 'specverse_expand_constraint',
+        description: 'Expand a behavioural constraint string into a Quint invariant. Example: "models must have attributes"',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            constraint: {
+              type: 'string',
+              description: 'Human-readable constraint to expand (e.g., "models must have attributes")',
+            },
+          },
+          required: ['constraint'],
+        },
+      },
+      {
+        name: 'specverse_list_conventions',
+        description: 'List available behavioural conventions for a specific entity type',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            entity: {
+              type: 'string',
+              description: 'Entity type (e.g., "models", "controllers", "services")',
+            },
+          },
+          required: ['entity'],
+        },
+      },
+      {
+        name: 'specverse_entity_info',
+        description: 'Get detailed metadata about an entity module (conventions, inference rules, diagram plugins)',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            entity: {
+              type: 'string',
+              description: 'Entity name (e.g., "models", "controllers", "deployments")',
+            },
+          },
+          required: ['entity'],
+        },
+      },
+    ];
+  }
+
+  /**
+   * Execute an entity module tool.
+   */
+  async executeTool(name: string, args: Record<string, any>): Promise<MCPToolResult> {
+    switch (name) {
+      case 'specverse_expand_constraint': {
+        const result = this.expandConstraint(args.constraint);
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(result, null, 2),
+          }],
+        };
+      }
+
+      case 'specverse_list_conventions': {
+        const grammars = this.getConventionGrammars();
+        const grammar = grammars.find(g => g.entity === args.entity);
+        if (!grammar) {
+          return {
+            content: [{
+              type: 'text',
+              text: `No conventions found for entity "${args.entity}". Available: ${grammars.map(g => g.entity).join(', ')}`,
+            }],
+          };
+        }
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(grammar, null, 2),
+          }],
+        };
+      }
+
+      case 'specverse_entity_info': {
+        const modules = this.getEntityModules();
+        const mod = modules.find(m => m.name === args.entity);
+        if (!mod) {
+          return {
+            content: [{
+              type: 'text',
+              text: `Entity "${args.entity}" not found. Available: ${modules.map(m => m.name).join(', ')}`,
+            }],
+          };
+        }
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(mod, null, 2),
+          }],
+        };
+      }
+
+      default:
+        return {
+          content: [{
+            type: 'text',
+            text: `Unknown entity module tool: ${name}`,
+          }],
+        };
+    }
+  }
+}