@specverse/engines 4.1.0

package/libs/instance-factories/applications/templates/react/tailwind-adapter-wrapper-generator.ts

@@ -0,0 +1,84 @@
+/**
+ * Tailwind Adapter Wrapper Generator
+ *
+ * Bundles the tailwind-adapter-generator.ts source file for generated projects.
+ * This file is imported by react-pattern-adapter.tsx.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+export interface TailwindAdapterGeneratorContext {
+  spec: any;
+  manifest: any;
+}
+
+export async function generate(context: TailwindAdapterGeneratorContext): Promise<string> {
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+
+  // Try to find the tailwind-adapter-generator.ts source file
+  const possiblePaths = [
+    // PRIORITY 1: Bundled with package (in libs/ directory)
+    join(__dirname, '../../../../../../libs/instance-factories/applications/templates/react/tailwind-adapter-generator.ts'),
+    // PRIORITY 2: Development environment (local)
+    join(__dirname, './tailwind-adapter-generator.ts'),
+    join(__dirname, '../tailwind-adapter-generator.ts')
+  ];
+
+  let adapterSource: string | null = null;
+  let foundPath: string | null = null;
+
+  for (const path of possiblePaths) {
+    if (existsSync(path)) {
+      try {
+        adapterSource = readFileSync(path, 'utf-8');
+        foundPath = path;
+        break;
+      } catch (error) {
+        // Continue to next path
+      }
+    }
+  }
+
+  if (adapterSource) {
+    // Successfully read the adapter - return it with a header comment
+    return `/**
+ * Universal Tailwind Adapter Generator
+ *
+ * AUTO-GENERATED: Copied from @specverse/lang
+ * Source: ${foundPath}
+ *
+ * This file provides Tailwind CSS rendering for all atomic component types.
+ * It is imported by react-pattern-adapter.tsx.
+ *
+ * DO NOT EDIT: Changes will be overwritten on next generation.
+ */
+
+${adapterSource}
+`;
+  }
+
+  // Fallback: Return minimal stub (should never happen with bundled source)
+  return `/**
+ * Tailwind Adapter Generator (STUB)
+ *
+ * ⚠️ WARNING: Could not locate tailwind-adapter-generator.ts source file.
+ */
+
+import type { ComponentAdapter } from '@specverse/lang';
+
+export function createUniversalTailwindAdapter(): ComponentAdapter {
+  return {
+    renderComponent(type: string, properties: Record<string, any> = {}, children?: string): string {
+      return \`<div class="p-4 border border-gray-300 rounded bg-gray-50">
+        <span class="text-gray-700">\${type}</span>
+      </div>\`;
+    }
+  };
+}
+
+console.warn('⚠️ Using stub Tailwind adapter - full source file not found during generation');
+`;
+}

package/libs/instance-factories/applications/templates/react/tsconfig-generator.ts

@@ -0,0 +1,35 @@
+/**
+ * TSConfig Generator for React App
+ *
+ * Generates TypeScript configuration for frontend
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+export default function generateTsConfig(context: TemplateContext): string {
+  return JSON.stringify({
+    compilerOptions: {
+      target: "ES2020",
+      useDefineForClassFields: true,
+      lib: ["ES2020", "DOM", "DOM.Iterable"],
+      module: "ESNext",
+      skipLibCheck: true,
+      types: ["vite/client"],
+
+      /* Bundler mode */
+      moduleResolution: "bundler",
+      allowImportingTsExtensions: true,
+      resolveJsonModule: true,
+      isolatedModules: true,
+      noEmit: true,
+      jsx: "react-jsx",
+
+      /* Linting */
+      strict: true,
+      noUnusedLocals: true,
+      noUnusedParameters: true,
+      noFallthroughCasesInSwitch: true
+    },
+    include: ["src"]
+  }, null, 2);
+}

package/libs/instance-factories/applications/templates/react/use-api-hooks-generator.ts

@@ -0,0 +1,121 @@
+/**
+ * useApi Hooks Generator
+ * Generates React Query hooks for API operations in generated projects
+ */
+
+export interface UseApiHooksGeneratorContext {
+  spec: any;
+  manifest: any;
+}
+
+export async function generate(context: UseApiHooksGeneratorContext): Promise<string> {
+  return `/**
+ * useApi - React Query Hooks
+ *
+ * Custom hooks for API operations using React Query
+ * Simplified version for generated projects (no Zustand store dependency)
+ */
+
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import {
+  getModelSchema,
+  listEntities,
+  executeOperation,
+  transitionState
+} from '../lib/apiClient';
+import type { ModelSchema, Entity, ApiResponse } from '../types/api';
+
+/**
+ * Query hook for model schema
+ */
+export function useModelSchemaQuery(modelName: string | null) {
+  return useQuery({
+    queryKey: ['modelSchema', modelName],
+    queryFn: async (): Promise<ModelSchema> => {
+      if (!modelName) throw new Error('Model name is required');
+      return await getModelSchema(modelName);
+    },
+    enabled: !!modelName,
+    staleTime: 5 * 60 * 1000,  // Cache for 5 minutes
+    refetchOnWindowFocus: false  // Schema rarely changes
+  });
+}
+
+/**
+ * Query hook for entities
+ */
+export function useEntitiesQuery(controllerName: string | null, modelName: string | null) {
+  return useQuery({
+    queryKey: ['entities', modelName],
+    queryFn: async (): Promise<Entity[]> => {
+      if (!controllerName || !modelName) {
+        throw new Error('Controller and model names are required');
+      }
+      return await listEntities(controllerName);
+    },
+    enabled: !!controllerName && !!modelName,
+    refetchInterval: 5000  // Refetch every 5 seconds for real-time feel
+  });
+}
+
+/**
+ * Mutation hook for executing operations
+ */
+export function useExecuteOperationMutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({
+      controllerName,
+      operationName,
+      params
+    }: {
+      controllerName: string;
+      operationName: string;
+      params: Record<string, any>;
+    }): Promise<ApiResponse> => executeOperation(controllerName, operationName, params),
+    onSuccess: (_data, variables) => {
+      // Invalidate entities query to refetch
+      const modelName = variables.controllerName.replace(/Controller$/, '');
+      queryClient.invalidateQueries({ queryKey: ['entities', modelName] });
+    }
+  });
+}
+
+/**
+ * Mutation hook for lifecycle transitions
+ */
+export function useTransitionStateMutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({
+      modelName,
+      entityId,
+      toState,
+      lifecycleName
+    }: {
+      modelName: string;
+      entityId: string;
+      toState: string;
+      lifecycleName?: string;
+    }): Promise<ApiResponse> => transitionState(modelName, entityId, toState, lifecycleName),
+    onSuccess: (_data, variables) => {
+      // Invalidate entities query to refetch
+      queryClient.invalidateQueries({ queryKey: ['entities', variables.modelName] });
+    }
+  });
+}
+
+/**
+ * Hook for invalidating all queries (useful for manual refresh)
+ */
+export function useInvalidateAll() {
+  const queryClient = useQueryClient();
+
+  return () => {
+    queryClient.invalidateQueries();
+  };
+}
+`;
+}

package/libs/instance-factories/applications/templates/react/view-dashboard-generator.ts

@@ -0,0 +1,150 @@
+/**
+ * DashboardView Generator (Pattern-Based v0.9.0)
+ * Generates pattern-based DashboardView using RuntimeView architecture
+ */
+
+export interface ViewDashboardGeneratorContext {
+  spec: any;
+  manifest: any;
+}
+
+export async function generate(context: ViewDashboardGeneratorContext): Promise<string> {
+  return `/**
+ * DashboardView - Pattern-Based Dashboard View Component
+ *
+ * Uses pattern-based rendering with ReactPatternAdapter.
+ * Supports multi-component dashboard layouts with entity selection.
+ */
+
+import { useState, useEffect, useMemo } from 'react';
+import { useEntitiesQuery, useModelSchemaQuery } from '../../hooks/useApi';
+import { usePatternAdapter, REACT_PROTOCOL_MAPPING } from '../../lib/react-pattern-adapter';
+import type { View } from '../../types/api';
+
+interface DashboardViewProps {
+  view: View;
+  spec?: any;
+}
+
+export function DashboardView({ view, spec }: DashboardViewProps) {
+  const patternAdapter = usePatternAdapter();
+
+  // Determine controller and model
+  let controllerName: string;
+  let modelName: string;
+
+  if (view.controller && spec) {
+    controllerName = view.controller;
+    const controller = spec.controllers[view.controller];
+    modelName = controller.model;
+  } else {
+    modelName = view.model as string;
+    controllerName = \`\${modelName}Controller\`;
+  }
+
+  // Fetch data and schema
+  const { data: entities = [] } = useEntitiesQuery(controllerName, modelName);
+  const { data: schema } = useModelSchemaQuery(modelName);
+
+  // Track selected entity
+  const [selectedEntityId, setSelectedEntityId] = useState<string | null>(
+    entities.length > 0 ? entities[0].id : null
+  );
+
+  // Update selected entity when entities change
+  useEffect(() => {
+    if (entities.length > 0 && !selectedEntityId) {
+      setSelectedEntityId(entities[0].id);
+    }
+  }, [entities, selectedEntityId]);
+
+  // Get selected entity
+  const selectedEntity = useMemo(
+    () => entities.find((e: any) => e.id === selectedEntityId) || null,
+    [entities, selectedEntityId]
+  );
+
+  // Build model data and schemas
+  const modelData = useMemo(() => ({
+    [modelName]: entities
+  }), [modelName, entities]);
+
+  const modelSchemas = useMemo(() =>
+    schema ? { [modelName]: schema } : {}
+  , [modelName, schema]);
+
+  if (entities.length === 0) {
+    return <div className="p-4">No entities found</div>;
+  }
+
+  // Detect pattern
+  const pattern = patternAdapter.detectPattern({ ...view, type: 'dashboard' });
+
+  if (!pattern) {
+    return (
+      <div className="p-4 text-red-600">
+        Pattern not found for dashboard view
+      </div>
+    );
+  }
+
+  // Build render context
+  const context = {
+    pattern,
+    viewSpec: { ...view, type: 'dashboard', model: modelName },
+    modelData,
+    modelSchemas,
+    primaryModel: modelName,
+    selectedEntity,
+    primaryEntities: entities,
+    protocolMapping: REACT_PROTOCOL_MAPPING,
+    tailwindAdapter: patternAdapter['tailwindAdapter']
+  };
+
+  // Render entity selector
+  let html = '';
+  if (entities.length > 0) {
+    html += \`
+      <div class="mb-4 pb-4 border-b border-gray-200 dark:border-gray-700">
+        <label class="block text-sm font-semibold text-gray-700 dark:text-gray-200 mb-2">
+          Select \${modelName}:
+        </label>
+        <select
+          id="entity-selector"
+          class="w-full max-w-md px-3 py-2 border border-gray-300 dark:border-gray-600 rounded bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-2 focus:ring-blue-500"
+        >
+          \${entities.map((entity: any) => {
+            const displayName = entity.data?.name || entity.data?.title || entity.id;
+            return \`<option value="\${entity.id}" \${entity.id === selectedEntityId ? 'selected' : ''}>\${displayName}</option>\`;
+          }).join('')}
+        </select>
+      </div>
+    \`;
+  }
+
+  // Render pattern
+  html += patternAdapter.renderPattern(context);
+
+  // Add event handler for selector
+  useEffect(() => {
+    const selector = document.getElementById('entity-selector') as HTMLSelectElement;
+    if (selector) {
+      const handler = (e: Event) => {
+        const newId = (e.target as HTMLSelectElement).value;
+        setSelectedEntityId(newId);
+      };
+      selector.addEventListener('change', handler);
+      return () => selector.removeEventListener('change', handler);
+    }
+  }, [html]);
+
+  return (
+    <div className="runtime-view-container p-4 h-full overflow-auto">
+      <div dangerouslySetInnerHTML={{ __html: html }} />
+    </div>
+  );
+}
+
+export default DashboardView;
+`;
+}

package/libs/instance-factories/applications/templates/react/view-detail-generator.ts

@@ -0,0 +1,150 @@
+/**
+ * DetailView Generator (Pattern-Based v0.9.0)
+ * Generates pattern-based DetailView using RuntimeView architecture
+ */
+
+export interface ViewDetailGeneratorContext {
+  spec: any;
+  manifest: any;
+}
+
+export async function generate(context: ViewDetailGeneratorContext): Promise<string> {
+  return `/**
+ * DetailView - Pattern-Based Detail View Component
+ *
+ * Uses pattern-based rendering with ReactPatternAdapter.
+ * Supports entity selection and relationship display.
+ */
+
+import { useState, useEffect, useMemo } from 'react';
+import { useEntitiesQuery, useModelSchemaQuery } from '../../hooks/useApi';
+import { usePatternAdapter, REACT_PROTOCOL_MAPPING } from '../../lib/react-pattern-adapter';
+import type { View } from '../../types/api';
+
+interface DetailViewProps {
+  view: View;
+  spec?: any;
+}
+
+export function DetailView({ view, spec }: DetailViewProps) {
+  const patternAdapter = usePatternAdapter();
+
+  // Determine controller and model
+  let controllerName: string;
+  let modelName: string;
+
+  if (view.controller && spec) {
+    controllerName = view.controller;
+    const controller = spec.controllers[view.controller];
+    modelName = controller.model;
+  } else {
+    modelName = view.model as string;
+    controllerName = \`\${modelName}Controller\`;
+  }
+
+  // Fetch data and schema
+  const { data: entities = [] } = useEntitiesQuery(controllerName, modelName);
+  const { data: schema } = useModelSchemaQuery(modelName);
+
+  // Track selected entity
+  const [selectedEntityId, setSelectedEntityId] = useState<string | null>(
+    entities.length > 0 ? entities[0].id : null
+  );
+
+  // Update selected entity when entities change
+  useEffect(() => {
+    if (entities.length > 0 && !selectedEntityId) {
+      setSelectedEntityId(entities[0].id);
+    }
+  }, [entities, selectedEntityId]);
+
+  // Get selected entity
+  const selectedEntity = useMemo(
+    () => entities.find((e: any) => e.id === selectedEntityId) || null,
+    [entities, selectedEntityId]
+  );
+
+  // Build model data and schemas
+  const modelData = useMemo(() => ({
+    [modelName]: entities
+  }), [modelName, entities]);
+
+  const modelSchemas = useMemo(() =>
+    schema ? { [modelName]: schema } : {}
+  , [modelName, schema]);
+
+  if (entities.length === 0) {
+    return <div className="p-4">No entities found</div>;
+  }
+
+  // Detect pattern
+  const pattern = patternAdapter.detectPattern({ ...view, type: 'detail' });
+
+  if (!pattern) {
+    return (
+      <div className="p-4 text-red-600">
+        Pattern not found for detail view
+      </div>
+    );
+  }
+
+  // Build render context
+  const context = {
+    pattern,
+    viewSpec: { ...view, type: 'detail', model: modelName },
+    modelData,
+    modelSchemas,
+    primaryModel: modelName,
+    selectedEntity,
+    primaryEntities: entities,
+    protocolMapping: REACT_PROTOCOL_MAPPING,
+    tailwindAdapter: patternAdapter['tailwindAdapter']
+  };
+
+  // Render entity selector
+  let html = '';
+  if (entities.length > 0) {
+    html += \`
+      <div class="mb-4 pb-4 border-b border-gray-200 dark:border-gray-700">
+        <label class="block text-sm font-semibold text-gray-700 dark:text-gray-200 mb-2">
+          Select \${modelName}:
+        </label>
+        <select
+          id="entity-selector"
+          class="w-full max-w-md px-3 py-2 border border-gray-300 dark:border-gray-600 rounded bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-2 focus:ring-blue-500"
+        >
+          \${entities.map((entity: any) => {
+            const displayName = entity.data?.name || entity.data?.title || entity.id;
+            return \`<option value="\${entity.id}" \${entity.id === selectedEntityId ? 'selected' : ''}>\${displayName}</option>\`;
+          }).join('')}
+        </select>
+      </div>
+    \`;
+  }
+
+  // Render pattern
+  html += patternAdapter.renderPattern(context);
+
+  // Add event handler for selector
+  useEffect(() => {
+    const selector = document.getElementById('entity-selector') as HTMLSelectElement;
+    if (selector) {
+      const handler = (e: Event) => {
+        const newId = (e.target as HTMLSelectElement).value;
+        setSelectedEntityId(newId);
+      };
+      selector.addEventListener('change', handler);
+      return () => selector.removeEventListener('change', handler);
+    }
+  }, [html]);
+
+  return (
+    <div className="runtime-view-container p-4 h-full overflow-auto">
+      <div dangerouslySetInnerHTML={{ __html: html }} />
+    </div>
+  );
+}
+
+export default DetailView;
+`;
+}