@specverse/engines 4.1.0

package/libs/instance-factories/views/templates/react/router-generator.ts

@@ -0,0 +1,197 @@
+/**
+ * React Router Setup Generator
+ *
+ * Generates router.tsx with routes based on spec views
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+/**
+ * Generate router.tsx with React Router v6 setup
+ */
+export default function generateRouter(context: TemplateContext): string {
+  const { spec, models = [], views = [] } = context;
+
+  // Extract views from spec if not provided
+  const specViews = views.length > 0 ? views : (spec?.views ? Object.entries(spec.views) : []);
+
+  // Generate imports
+  const imports: string[] = [];
+  const routes: string[] = [];
+
+  // Add home route
+  routes.push(`  {
+    path: '/',
+    element: <div className="home-page">
+      <h1>Welcome</h1>
+      <nav>
+        <ul>
+${generateHomeLinks(specViews, models)}
+        </ul>
+      </nav>
+    </div>
+  }`);
+
+  // Track used paths to ensure uniqueness
+  const usedPaths = new Set<string>();
+
+  // Generate routes for each view
+  specViews.forEach((viewEntry: any) => {
+    const [viewName, viewDef] = Array.isArray(viewEntry) ? viewEntry : [viewEntry.name, viewEntry];
+
+    // Determine route pattern based on view type
+    const viewType = viewDef?.type || 'list';
+    const model = Array.isArray(viewDef?.model) ? viewDef.model[0] : viewDef?.model;
+
+    if (!model) return;
+
+    const modelLower = model.toLowerCase();
+    const modelPlural = modelLower + 's'; // Simple pluralization
+
+    imports.push(`import ${viewName} from './components/${viewName}';`);
+
+    // Generate unique path based on view name and type
+    const basePath = `/${modelPlural}`;
+
+    switch (viewType) {
+      case 'list':
+        // Use view name to create unique path if multiple list views
+        const listPath = usedPaths.has(basePath)
+          ? `${basePath}/${viewName.toLowerCase().replace(/view$/, '')}`
+          : basePath;
+
+        if (!usedPaths.has(listPath)) {
+          routes.push(`  {
+    path: '${listPath}',
+    element: <${viewName} />
+  }`);
+          usedPaths.add(listPath);
+        }
+        break;
+
+      case 'detail':
+        const detailPath = `${basePath}/:id`;
+        if (!usedPaths.has(detailPath)) {
+          routes.push(`  {
+    path: '${detailPath}',
+    element: <${viewName} />
+  }`);
+          usedPaths.add(detailPath);
+        }
+        break;
+
+      case 'form':
+        const newPath = `${basePath}/new`;
+        const editPath = `${basePath}/:id/edit`;
+
+        if (!usedPaths.has(newPath)) {
+          routes.push(`  {
+    path: '${newPath}',
+    element: <${viewName} />
+  }`);
+          usedPaths.add(newPath);
+        }
+
+        if (!usedPaths.has(editPath)) {
+          routes.push(`  {
+    path: '${editPath}',
+    element: <${viewName} />
+  }`);
+          usedPaths.add(editPath);
+        }
+        break;
+
+      case 'dashboard':
+        // Use model name in dashboard path for uniqueness
+        const dashPath = modelLower === 'author' || modelLower === 'user'
+          ? '/dashboard'
+          : `/dashboard/${modelLower}`;
+
+        if (!usedPaths.has(dashPath)) {
+          routes.push(`  {
+    path: '${dashPath}',
+    element: <${viewName} />
+  }`);
+          usedPaths.add(dashPath);
+        }
+        break;
+    }
+  });
+
+  return `/**
+ * React Router Configuration
+ * Auto-generated by SpecVerse
+ */
+
+import { createBrowserRouter } from 'react-router-dom';
+${imports.join('\n')}
+
+/**
+ * Application Router
+ */
+export const router = createBrowserRouter([
+${routes.join(',\n')}
+]);
+`;
+}
+
+/**
+ * Generate navigation links for home page
+ */
+function generateHomeLinks(views: any[], models: any[]): string {
+  const links: string[] = [];
+  const usedPaths = new Set<string>();
+
+  views.forEach((viewEntry: any) => {
+    const [viewName, viewDef] = Array.isArray(viewEntry) ? viewEntry : [viewEntry.name, viewEntry];
+    const viewType = viewDef?.type || 'list';
+    const model = Array.isArray(viewDef?.model) ? viewDef.model[0] : viewDef?.model;
+
+    if (!model) return;
+
+    const modelLower = model.toLowerCase();
+    const modelPlural = modelLower + 's';
+    const basePath = `/${modelPlural}`;
+
+    // Generate descriptive label from view name
+    const viewLabel = viewName.replace(/View$/, '').replace(/([A-Z])/g, ' $1').trim();
+
+    switch (viewType) {
+      case 'list':
+        const listPath = usedPaths.has(basePath)
+          ? `${basePath}/${viewName.toLowerCase().replace(/view$/, '')}`
+          : basePath;
+
+        if (!usedPaths.has(listPath)) {
+          links.push(`          <li><a href="${listPath}">${viewLabel}</a></li>`);
+          usedPaths.add(listPath);
+        }
+        break;
+
+      case 'form':
+        const formPath = `${basePath}/new`;
+        if (!usedPaths.has(formPath)) {
+          links.push(`          <li><a href="${formPath}">Create ${model}</a></li>`);
+          usedPaths.add(formPath);
+        }
+        break;
+
+      case 'dashboard':
+        const dashPath = modelLower === 'author' || modelLower === 'user'
+          ? '/dashboard'
+          : `/dashboard/${modelLower}`;
+
+        if (!usedPaths.has(dashPath)) {
+          links.push(`          <li><a href="${dashPath}">${viewLabel}</a></li>`);
+          usedPaths.add(dashPath);
+        }
+        break;
+
+      case 'detail':
+        // Don't add detail views to home links (they require IDs)
+        break;
+    }
+  });
+
+  return links.join('\n');
+}

package/libs/instance-factories/views/templates/react/router-generic-generator.ts

@@ -0,0 +1,132 @@
+/**
+ * React Router Generator (App Shell)
+ *
+ * Generates App.tsx with app-demo-quality navigation and routing.
+ * Matches app-demo's visual patterns: sidebar, active states, model grouping,
+ * specialist view links.
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+export default function generateRouter(context: TemplateContext): string {
+  const { spec, models = [], views = [] } = context;
+
+  const specViews = views.length > 0 ? views : (spec?.views || []);
+  const viewsArray = Array.isArray(specViews) ? specViews : Object.values(specViews);
+
+  // Collect view info grouped by model
+  const modelViews = new Map<string, Array<{ name: string; type: string; path: string }>>();
+  const viewImports: string[] = [];
+  const routeEntries: string[] = [];
+
+  viewsArray.forEach((viewDef: any) => {
+    const viewName = viewDef.name;
+    if (!viewName) return;
+    const model = Array.isArray(viewDef.model) ? viewDef.model[0] : viewDef.model;
+    if (!model) return;
+
+    const viewType = viewDef.type || 'list';
+    const modelLower = model.toLowerCase();
+    const path = `/${modelLower}${viewType}`;
+
+    viewImports.push(`import ${viewName} from './components/${viewName}';`);
+    routeEntries.push(`          <Route path="${path}" element={<${viewName} />} />`);
+
+    if (!modelViews.has(model)) modelViews.set(model, []);
+    modelViews.get(model)!.push({ name: viewName, type: viewType, path });
+  });
+
+  // Get app name from spec
+  const appName = spec?.componentName || spec?.metadata?.component || spec?.name || 'App';
+
+  // Build sidebar sections per model
+  const sidebarSections = Array.from(modelViews.entries()).map(([model, views]) => {
+    const lower = model.toLowerCase();
+    const listView = views.find(v => v.type === 'list');
+    const formView = views.find(v => v.type === 'form');
+    const specialistViews = views.filter(v => !['list', 'detail', 'form'].includes(v.type));
+
+    const specialistLinks = specialistViews.map(v => {
+      const label = v.type.charAt(0).toUpperCase() + v.type.slice(1);
+      const icon = v.type === 'board' ? '▦' : v.type === 'timeline' ? '⏱' : v.type === 'calendar' ? '📅' : v.type === 'dashboard' ? '📊' : v.type === 'analytics' ? '📈' : '◆';
+      return `              <Link to="${v.path}" className={\`flex items-center gap-2 px-2 py-1.5 rounded text-sm transition-all \${location.pathname === '${v.path}' ? 'bg-blue-50 text-blue-700 font-medium border border-blue-200' : 'text-gray-600 hover:bg-gray-50 hover:text-gray-900 border border-transparent'}\`}>
+                <span className="text-xs">${icon}</span> ${label}
+              </Link>`;
+    }).join('\n');
+
+    return `          {/* ${model} */}
+          <div>
+            <h3 className="px-2 text-xs font-semibold text-gray-400 uppercase tracking-wider mb-1">${model}s</h3>
+            <div className="space-y-0.5">
+${listView ? `              <Link to="${listView.path}" className={\`flex items-center gap-2 px-2 py-1.5 rounded text-sm transition-all \${location.pathname === '${listView.path}' ? 'bg-blue-50 text-blue-700 font-medium border border-blue-200' : 'text-gray-700 hover:bg-gray-50 border border-transparent'}\`}>
+                <span className="text-xs">☰</span> Browse
+              </Link>` : ''}
+${formView ? `              <Link to="${formView.path}" className={\`flex items-center gap-2 px-2 py-1.5 rounded text-sm transition-all \${location.pathname === '${formView.path}' ? 'bg-blue-50 text-blue-700 font-medium border border-blue-200' : 'text-gray-700 hover:bg-gray-50 border border-transparent'}\`}>
+                <span className="text-xs">＋</span> New
+              </Link>` : ''}
+${specialistLinks}
+            </div>
+          </div>`;
+  }).join('\n\n');
+
+  // Default route
+  const firstModel = Array.from(modelViews.keys())[0]?.toLowerCase() || 'unknown';
+  const hasDashboard = viewsArray.some((v: any) => v.type === 'dashboard');
+  const defaultElement = hasDashboard
+    ? viewsArray.find((v: any) => v.type === 'dashboard')?.name || `${Array.from(modelViews.keys())[0]}ListView`
+    : `${Array.from(modelViews.keys())[0] || 'Unknown'}ListView`;
+
+  return `import { BrowserRouter as Router, Routes, Route, Link, useLocation } from 'react-router-dom';
+${viewImports.join('\n')}
+
+function Sidebar() {
+  const location = useLocation();
+  return (
+    <aside className="w-60 bg-white border-r border-gray-200 flex flex-col">
+      {/* App Header */}
+      <div className="px-4 py-5 border-b border-gray-100">
+        <h1 className="text-lg font-bold text-gray-900">${appName}</h1>
+        <p className="text-xs text-gray-400 mt-0.5">Generated from specification</p>
+      </div>
+
+      {/* Navigation */}
+      <nav className="flex-1 overflow-y-auto px-3 py-4 space-y-5">
+${sidebarSections}
+      </nav>
+
+      {/* Footer */}
+      <div className="px-4 py-3 border-t border-gray-100 text-xs text-gray-400">
+        Powered by SpecVerse
+      </div>
+    </aside>
+  );
+}
+
+function App() {
+  return (
+    <Router>
+      <div className="flex h-screen bg-gray-50 overflow-hidden">
+        <Sidebar />
+        <main className="flex-1 overflow-y-auto">
+          <Routes>
+            <Route path="/" element={<${defaultElement} />} />
+${routeEntries.join('\n')}
+            <Route path="*" element={
+              <div className="flex items-center justify-center h-full">
+                <div className="text-center">
+                  <h1 className="text-4xl font-bold text-gray-300 mb-2">404</h1>
+                  <p className="text-gray-500">Page not found</p>
+                  <Link to="/" className="mt-4 inline-block text-blue-600 hover:text-blue-700 text-sm">← Back to home</Link>
+                </div>
+              </div>
+            } />
+          </Routes>
+        </main>
+      </div>
+    </Router>
+  );
+}
+
+export default App;
+`;
+}

package/libs/instance-factories/views/templates/react/shared-utils-generator.ts

@@ -0,0 +1,188 @@
+/**
+ * Shared Utilities Generator
+ *
+ * Generates field-helpers.ts, relationship-utils.ts, and view-helpers.ts
+ * into the frontend's src/lib/ directory. These are imported by all view components.
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+export default function generateSharedUtils(context: TemplateContext): { files: Array<{ path: string; content: string }> } {
+  const files = [
+    { path: 'field-helpers.ts', content: generateFieldHelpers() },
+    { path: 'view-helpers.tsx', content: generateViewHelpers() },
+  ];
+
+  return { files };
+}
+
+function generateFieldHelpers(): string {
+  return `/**
+ * Field Helpers — shared utilities for field classification and display
+ * Generated by SpecVerse React factory
+ */
+
+const METADATA_FIELDS = new Set([
+  'id', 'createdAt', 'updatedAt', 'createdBy', 'updatedBy', 'deletedAt', 'version'
+]);
+
+const AUTO_PATTERNS = new Set(['now', 'uuid4', 'autoincrement', 'auto']);
+
+/**
+ * Check if a field is auto-generated (should be hidden from forms)
+ */
+export function isAutoField(name: string, attr: any): boolean {
+  if (attr?.auto && AUTO_PATTERNS.has(attr.auto)) return true;
+  if (name === 'id') return true;
+  if (METADATA_FIELDS.has(name) && attr?.type?.toLowerCase().includes('date')) return true;
+  return false;
+}
+
+/**
+ * Check if a field is metadata (shown last, styled muted)
+ */
+export function isMetadataField(name: string): boolean {
+  return METADATA_FIELDS.has(name);
+}
+
+/**
+ * Get the best display name for an entity
+ * Searches common name fields in priority order
+ */
+export function getEntityDisplayName(entity: any): string {
+  if (!entity) return 'Unknown';
+  for (const field of ['name', 'title', 'displayName', 'label', 'username', 'email', 'subject']) {
+    if (entity[field]) return String(entity[field]);
+  }
+  return entity.id ? String(entity.id).slice(0, 8) + '...' : 'Unknown';
+}
+
+/**
+ * Classify attributes into ordered groups for display
+ */
+export function classifyFields(attributes: Array<{ name: string; type: string; auto?: string; required?: boolean }>): {
+  business: typeof attributes;
+  lifecycle: typeof attributes;
+  metadata: typeof attributes;
+} {
+  const business: typeof attributes = [];
+  const lifecycle: typeof attributes = [];
+  const metadata: typeof attributes = [];
+
+  for (const attr of attributes) {
+    if (isAutoField(attr.name, attr) || isMetadataField(attr.name)) {
+      metadata.push(attr);
+    } else if (attr.name === 'status' || attr.name === 'state' || attr.name === 'phase') {
+      lifecycle.push(attr);
+    } else {
+      business.push(attr);
+    }
+  }
+
+  return { business, lifecycle, metadata };
+}
+`;
+}
+
+function generateViewHelpers(): string {
+  return `/**
+ * View Helpers — formatting, colors, and UI utilities
+ * Generated by SpecVerse React factory
+ */
+
+/**
+ * Format a value for display
+ */
+export function formatValue(value: any, type?: string): string {
+  if (value === null || value === undefined) return '—';
+  if (type?.toLowerCase().includes('date') || type?.toLowerCase().includes('timestamp')) {
+    return formatDate(value);
+  }
+  if (typeof value === 'boolean') return value ? 'Yes' : 'No';
+  return String(value);
+}
+
+/**
+ * Format a date for display (relative for recent, absolute for old)
+ */
+export function formatDate(value: any): string {
+  if (!value) return '—';
+  const date = new Date(value);
+  if (isNaN(date.getTime())) return String(value);
+
+  const now = new Date();
+  const diff = now.getTime() - date.getTime();
+  const minutes = Math.floor(diff / 60000);
+  const hours = Math.floor(diff / 3600000);
+  const days = Math.floor(diff / 86400000);
+
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return \`\${minutes}m ago\`;
+  if (hours < 24) return \`\${hours}h ago\`;
+  if (days < 7) return \`\${days}d ago\`;
+  return date.toLocaleDateString();
+}
+
+/**
+ * Truncate text with ellipsis
+ */
+export function truncate(text: string, max: number = 60): string {
+  if (!text || text.length <= max) return text;
+  return text.slice(0, max) + '...';
+}
+
+/**
+ * Get a Tailwind color class for a lifecycle status
+ */
+export function statusColor(status: string): { bg: string; text: string; dot: string } {
+  const s = status?.toLowerCase().replace(/[_-]/g, '') || '';
+
+  // Green states
+  if (['active', 'done', 'completed', 'approved', 'published', 'resolved'].includes(s)) {
+    return { bg: 'bg-green-50', text: 'text-green-700', dot: 'bg-green-500' };
+  }
+  // Blue states
+  if (['inprogress', 'processing', 'review', 'pending'].includes(s)) {
+    return { bg: 'bg-blue-50', text: 'text-blue-700', dot: 'bg-blue-500' };
+  }
+  // Yellow states
+  if (['draft', 'todo', 'planning', 'waiting', 'scheduled'].includes(s)) {
+    return { bg: 'bg-yellow-50', text: 'text-yellow-700', dot: 'bg-yellow-500' };
+  }
+  // Red states
+  if (['cancelled', 'rejected', 'failed', 'overdue', 'blocked'].includes(s)) {
+    return { bg: 'bg-red-50', text: 'text-red-700', dot: 'bg-red-500' };
+  }
+  // Gray states
+  if (['archived', 'closed', 'deprecated', 'inactive', 'disabled'].includes(s)) {
+    return { bg: 'bg-gray-50', text: 'text-gray-500', dot: 'bg-gray-400' };
+  }
+  // Default: indigo
+  return { bg: 'bg-indigo-50', text: 'text-indigo-700', dot: 'bg-indigo-500' };
+}
+
+/**
+ * StatusBadge component — matches app-demo's lifecycle badge styling
+ */
+export function StatusBadge({ status, variant = 'default' }: { status: string; variant?: 'default' | 'lifecycle' }) {
+  if (!status) return null;
+
+  // Lifecycle badges use purple (matching app-demo)
+  if (variant === 'lifecycle') {
+    return (
+      <span className="px-2 py-1 bg-purple-100 text-purple-700 rounded text-xs font-medium">
+        {status.replace(/[_-]/g, ' ')}
+      </span>
+    );
+  }
+
+  const colors = statusColor(status);
+  return (
+    <span className={\`inline-flex items-center gap-1.5 px-2 py-1 rounded text-xs font-medium \${colors.bg} \${colors.text}\`}>
+      <span className={\`w-1.5 h-1.5 rounded-full \${colors.dot}\`}></span>
+      {status.replace(/[_-]/g, ' ')}
+    </span>
+  );
+}
+`;
+}

package/libs/instance-factories/views/templates/react/spec-json-generator.ts

@@ -0,0 +1,17 @@
+/**
+ * Full Spec JSON Generator
+ *
+ * Generates spec.json with the complete AI-optimized specification
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+/**
+ * Generate spec.json - the complete AI-optimized spec
+ */
+export default function generateSpecJson(context: TemplateContext): string {
+  const { spec } = context;
+
+  // Return the full spec as formatted JSON
+  return JSON.stringify(spec, null, 2);
+}

package/libs/instance-factories/views/templates/react/types-generator.ts

@@ -0,0 +1,76 @@
+/**
+ * React TypeScript Types Generator
+ *
+ * Generates TypeScript interfaces from model definitions
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+/**
+ * Generate TypeScript interface for a model
+ */
+export default function generateModelTypes(context: TemplateContext): string {
+  const { model } = context;
+
+  if (!model) {
+    throw new Error('Model is required in template context');
+  }
+
+  const modelName = model.name;
+
+  // Convert attributes to object if it's an array
+  let attributes = model.attributes || {};
+  if (Array.isArray(attributes)) {
+    const obj: Record<string, any> = {};
+    attributes.forEach((attr: any) => {
+      if (attr && typeof attr === 'object' && attr.name) {
+        obj[attr.name] = attr;
+      } else if (Array.isArray(attr) && attr.length >= 2) {
+        obj[attr[0]] = attr[1];
+      }
+    });
+    attributes = obj;
+  }
+
+  // Generate interface properties
+  const properties = Object.entries(attributes).map(([name, attr]: [string, any]) => {
+    const tsType = mapToTypeScript(attr.type);
+    const optional = !attr.constraints?.required ? '?' : '';
+    return `  ${name}${optional}: ${tsType};`;
+  }).join('\n');
+
+  return `/**
+ * ${modelName} Type Definition
+ * Auto-generated from SpecVerse model
+ */
+
+export interface ${modelName} {
+${properties}
+}
+
+export type Create${modelName}Input = Omit<${modelName}, 'id' | 'createdAt' | 'updatedAt'>;
+export type Update${modelName}Input = Partial<Create${modelName}Input>;
+`;
+}
+
+/**
+ * Map SpecVerse types to TypeScript types
+ */
+function mapToTypeScript(type: string): string {
+  const typeMap: Record<string, string> = {
+    'String': 'string',
+    'Integer': 'number',
+    'Float': 'number',
+    'Boolean': 'boolean',
+    'Date': 'string',
+    'DateTime': 'string',
+    'Timestamp': 'string',
+    'UUID': 'string',
+    'Email': 'string',
+    'URL': 'string',
+    'JSON': 'Record<string, any>',
+    'Array': 'any[]',
+  };
+
+  return typeMap[type] || 'any';
+}

package/libs/instance-factories/views/templates/react/views-metadata-generator.ts

@@ -0,0 +1,42 @@
+/**
+ * Views Metadata JSON Generator
+ *
+ * Generates views-metadata.json with controller-based view definitions
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+/**
+ * Generate views-metadata.json
+ */
+export default function generateViewsMetadata(context: TemplateContext): string {
+  const { spec, views = [] } = context;
+
+  // Extract views from spec if not provided
+  const specViews = views.length > 0 ? views : (spec?.views || []);
+  const viewsArray = Array.isArray(specViews) ? specViews : Object.values(specViews);
+
+  // Build metadata object
+  const metadata: Record<string, any> = {};
+
+  viewsArray.forEach((viewDef: any) => {
+    const viewName = viewDef.name;
+
+    // Extract only the essential metadata for runtime
+    metadata[viewName] = {
+      name: viewName,
+      type: viewDef.type || 'list',
+      ...(viewDef.description && { description: viewDef.description }),
+      model: viewDef.model,  // Keep as-is (string or array for multi-model views)
+      ...(viewDef.uiComponents && { uiComponents: viewDef.uiComponents }),
+      ...(viewDef.subscriptions && viewDef.subscriptions.length > 0 && {
+        subscriptions: viewDef.subscriptions
+      }),
+      routing: viewDef.routing || {
+        path: `/${viewName.toLowerCase().replace(/view$/, '')}`
+      }
+    };
+  });
+
+  return JSON.stringify(metadata, null, 2);
+}

package/libs/instance-factories/views/templates/react/vite-config-generator.ts

@@ -0,0 +1,38 @@
+/**
+ * Vite Configuration Generator
+ *
+ * Generates vite.config.ts for React application with backend proxy
+ */
+
+import type { TemplateContext } from '@specverse/types';
+
+/**
+ * Generate vite.config.ts
+ */
+export default function generateViteConfig(context: TemplateContext): string {
+  const { backendPort = 3000 } = context;
+
+  return `import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    host: true,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:${backendPort}',
+        changeOrigin: true,
+        rewrite: (path) => path
+      }
+    }
+  },
+  build: {
+    outDir: 'dist',
+    sourcemap: true
+  }
+});
+`;
+}