@specverse/engines 4.1.22 → 4.1.23

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

@@ -192,6 +192,7 @@ function pluralize(s: string): string {
 function generateListView(name: string, model: string, lower: string, plural: string, api: string, classified: ClassifiedAttrs, belongsTo: Rel[], lifecycle: Lifecycle | null, view: any): string {
   const displayCols = classified.business.slice(0, 5);
   const statusField = lifecycle?.statusField || classified.lifecycle[0]?.name;
+  const apiPath = api.replace(/^\/api/, ''); // strip /api prefix for apiRequest
 
   // Build relationship lookup fetches
   const relFetches = belongsTo.map(r => {
@@ -201,7 +202,7 @@ function generateListView(name: string, model: string, lower: string, plural: st
 
   const relEffects = belongsTo.map(r => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
-    return `    fetch('/api/${tLower}s').then(r => r.json()).then(data => {
+    return `    apiRequest('GET', '/${tLower}s').then(data => {
       if (Array.isArray(data)) {
         const m: Record<string, any> = {};
         data.forEach(e => { m[e.id] = e; });
@@ -218,6 +219,7 @@ function generateListView(name: string, model: string, lower: string, plural: st
 
   return `import { useState, useEffect } from 'react';
 import { Link } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { formatValue, formatDate, StatusBadge } from '../lib/view-helpers';
 
@@ -227,7 +229,7 @@ function ${name}() {
 ${relFetches}
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));
@@ -295,6 +297,7 @@ export default ${name};
 
 function generateDetailView(name: string, model: string, lower: string, plural: string, api: string, classified: ClassifiedAttrs, belongsTo: Rel[], hasMany: Rel[], lifecycle: Lifecycle | null, view: any): string {
   const statusField = lifecycle?.statusField || classified.lifecycle[0]?.name;
+  const apiPath = api.replace(/^\/api/, '');
 
   const relFetches = belongsTo.map(r => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
@@ -304,7 +307,7 @@ function generateDetailView(name: string, model: string, lower: string, plural:
   const relEffects = belongsTo.map(r => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
     const fk = `${r.name}_id`;
-    return `      if (data.${fk}) fetch(\`/api/${tLower}s/\${data.${fk}}\`).then(r => r.json()).then(d => set${r.target}Ref(d)).catch(() => {});`;
+    return `      if (data.${fk}) apiRequest('GET', \`/${tLower}s/\${data.${fk}}\`).then(d => set${r.target}Ref(d)).catch(() => {});`;
   }).join('\n');
 
   const hasManyFetches = hasMany.map(r => {
@@ -314,11 +317,12 @@ function generateDetailView(name: string, model: string, lower: string, plural:
 
   const hasManyEffects = hasMany.map(r => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
-    return `      fetch(\`/api/${tLower}s?${lower}Id=\${data.id}\`).then(r => r.json()).then(d => set${capitalize(r.name)}Items(Array.isArray(d) ? d : [])).catch(() => {});`;
+    return `      apiRequest('GET', \`/${tLower}s?${lower}Id=\${data.id}\`).then(d => set${capitalize(r.name)}Items(Array.isArray(d) ? d : [])).catch(() => {});`;
   }).join('\n');
 
   return `import { useState, useEffect } from 'react';
 import { Link, useSearchParams, useNavigate } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { formatValue, formatDate, StatusBadge } from '../lib/view-helpers';
 
@@ -333,7 +337,7 @@ ${hasManyFetches}
 
   useEffect(() => {
     if (!id) { setLoading(false); return; }
-    fetch(\`${api}/\${id}\`).then(r => r.ok ? r.json() : null).then(data => {
+    apiRequest('GET', \`${apiPath}/\${id}\`).then(data => {
       setItem(data);
       setLoading(false);
       if (data) {
@@ -348,7 +352,7 @@ ${hasManyEffects}
 
   const handleDelete = async () => {
     if (!confirm('Delete this ${lower}?')) return;
-    await fetch(\`${api}/\${id}\`, { method: 'DELETE' });
+    await apiRequest('DELETE', \`${apiPath}/\${id}\`);
     navigate('/${lower}list');
   };
 
@@ -436,6 +440,7 @@ function generateFormView(name: string, model: string, lower: string, plural: st
   // Only show editable fields (business + lifecycle, not metadata/auto)
   const editableFields = [...classified.business, ...classified.lifecycle];
   const statusField = lifecycle?.statusField;
+  const apiPath = api.replace(/^\/api/, '');
 
   const relStates = belongsTo.map(r => {
     return `  const [${r.target.charAt(0).toLowerCase() + r.target.slice(1)}Options, set${r.target}Options] = useState<any[]>([]);`;
@@ -443,7 +448,7 @@ function generateFormView(name: string, model: string, lower: string, plural: st
 
   const relEffects = belongsTo.map(r => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
-    return `    fetch('/api/${tLower}s').then(r => r.json()).then(d => set${r.target}Options(Array.isArray(d) ? d : [])).catch(() => {});`;
+    return `    apiRequest('GET', '/${tLower}s').then(d => set${r.target}Options(Array.isArray(d) ? d : [])).catch(() => {});`;
   }).join('\n');
 
   function inputForField(attr: Attr): string {
@@ -477,6 +482,7 @@ ${lifecycle.states.map(s => `          <option value="${s}">${s.replace(/[_-]/g,
 
   return `import { useState, useEffect } from 'react';
 import { useSearchParams, useNavigate } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 
 function ${name}() {
@@ -490,7 +496,7 @@ ${relStates}
 
   useEffect(() => {
     if (editId) {
-      fetch(\`${api}/\${editId}\`).then(r => r.json()).then(data => setForm(data || {})).catch(() => {});
+      apiRequest('GET', \`${apiPath}/\${editId}\`).then(data => setForm(data || {})).catch(() => {});
     }
 ${relEffects}
   }, [editId]);
@@ -505,17 +511,12 @@ ${relEffects}
     setSaving(true);
     setError('');
     try {
-      const method = editId ? 'PUT' : 'POST';
-      const url = editId ? \`${api}/\${editId}\` : '${api}';
-      const res = await fetch(url, {
-        method,
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(form),
-      });
-      if (!res.ok) {
-        const err = await res.json().catch(() => ({}));
-        throw new Error(err.message || 'Save failed');
+      if (editId) {
+        await apiRequest('PUT', \`${apiPath}/\${editId}\`, form);
+      } else {
+        await apiRequest('POST', '${apiPath}', form);
       }
+      // apiRequest throws on non-2xx so reaching here means success.
       navigate('/${lower}list');
     } catch (err: any) {
       setError(err.message);
@@ -582,8 +583,10 @@ export default ${name};
 function generateDashboardView(name: string, model: string, lower: string, plural: string, api: string, classified: ClassifiedAttrs, view: any, modelDef: any): string {
   const numericAttrs = classified.business.filter(a => ['integer', 'number', 'money', 'decimal', 'float'].includes(a.type.toLowerCase()));
   const metricNames = numericAttrs.map(a => a.name).slice(0, 4);
+  const apiPath = api.replace(/^\/api/, '');
 
   return `import { useState, useEffect } from 'react';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { formatDate, StatusBadge } from '../lib/view-helpers';
 
@@ -592,7 +595,7 @@ function ${name}() {
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));
@@ -650,9 +653,11 @@ export default ${name};
 function generateBoardView(name: string, model: string, lower: string, plural: string, api: string, lifecycle: Lifecycle | null, view: any): string {
   const states = lifecycle?.states || ['todo', 'in_progress', 'done'];
   const statusField = lifecycle?.statusField || 'status';
+  const apiPath = api.replace(/^\/api/, '');
 
   return `import { useState, useEffect } from 'react';
 import { Link } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { statusColor } from '../lib/view-helpers';
 
@@ -661,7 +666,7 @@ function ${name}() {
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));
@@ -718,8 +723,10 @@ export default ${name};
 // ============================================================================
 
 function generateTimelineView(name: string, model: string, lower: string, plural: string, api: string, view: any): string {
+  const apiPath = api.replace(/^\/api/, '');
   return `import { useState, useEffect } from 'react';
 import { Link } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { formatDate, StatusBadge } from '../lib/view-helpers';
 
@@ -728,7 +735,7 @@ function ${name}() {
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       const sorted = (Array.isArray(data) ? data : []).sort((a, b) =>
         new Date(b.createdAt || 0).getTime() - new Date(a.createdAt || 0).getTime()
       );
@@ -778,8 +785,10 @@ function generateCalendarView(name: string, model: string, lower: string, plural
   const dateField = attrs.find(a =>
     ['startdate', 'duedate', 'scheduledat', 'eventdate', 'date'].includes(a.name.toLowerCase())
   )?.name || 'createdAt';
+  const apiPath = api.replace(/^\/api/, '');
 
   return `import { useState, useEffect } from 'react';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 
 function ${name}() {
@@ -788,7 +797,7 @@ function ${name}() {
   const [currentMonth, setCurrentMonth] = useState(new Date());
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));
@@ -852,15 +861,17 @@ export default ${name};
 function generateAnalyticsView(name: string, model: string, lower: string, plural: string, api: string, classified: ClassifiedAttrs, lifecycle: Lifecycle | null, view: any, modelDef: any): string {
   const numericAttrs = classified.business.filter(a => ['integer', 'number', 'money', 'decimal', 'float'].includes(a.type.toLowerCase()));
   const statusField = lifecycle?.statusField || 'status';
+  const apiPath = api.replace(/^\/api/, '');
 
   return `import { useState, useEffect } from 'react';
+import { apiRequest } from '../lib/apiClient';
 
 function ${name}() {
   const [items, setItems] = useState<any[]>([]);
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));

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

@@ -1,16 +1,29 @@
 /**
- * React Hooks Generator
+ * React Hooks Generator — per-model convenience hook.
  *
- * Generates React custom hooks for data fetching and mutations
+ * Emits `use${Model}()` which is a thin delegator over the canonical
+ * hooks in `hooks/useApi.ts`. Historically this generator produced
+ * its own `useQuery(...)` + `useMutation(...)` blocks with private
+ * query keys (`['poll', id]`, `['polls', filters]`), which meant:
+ *
+ *   1. WebSocket events invalidating `['entities', modelName]` never
+ *      reached views that consumed this hook.
+ *   2. The conformance check `no-bare-usequery-in-views` lit up for
+ *      every per-model hook file.
+ *
+ * v2: delegate everything to `useEntitiesQuery` and
+ * `useExecuteOperationMutation` so there's exactly one cache key
+ * per model and one mutation pipeline across the whole frontend.
+ *
+ * The public API of `use${Model}()` is preserved for callers that
+ * depend on it: { [model], [models], isLoading, error, refetch,
+ * create, update, delete, isCreating, isUpdating, isDeleting }.
  */
 
 import type { TemplateContext } from '@specverse/types';
 
-/**
- * Generate React custom hook for a model
- */
 export default function generateReactHook(context: TemplateContext): string {
-  const { model, controller, spec } = context;
+  const { model } = context;
 
   if (!model) {
     throw new Error('Model is required in template context');
@@ -19,104 +32,75 @@ export default function generateReactHook(context: TemplateContext): string {
   const modelName = model.name;
   const hookName = `use${modelName}`;
   const controllerName = `${modelName}Controller`;
+  const singular = modelName.charAt(0).toLowerCase() + modelName.slice(1);
+  const plural = singular + 's';
 
   return `/**
  * ${hookName}
- * Custom React hook for ${modelName} data fetching and mutations
+ *
+ * Thin delegator over the canonical useApi hooks. All state flows
+ * through \`['entities', '${modelName}']\` so WebSocket invalidation
+ * reaches every view consuming this hook.
  */
 
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { executeOperation } from '../lib/apiClient';
+import { useMemo } from 'react';
+import {
+  useEntitiesQuery,
+  useExecuteOperationMutation,
+} from './useApi';
 import type { ${modelName} } from '../types/${modelName}';
 
-interface Use${modelName}Options {
+interface ${capitalize(hookName)}Options {
   id?: string;
   list?: boolean;
   filters?: Record<string, any>;
 }
 
-/**
- * ${hookName} - Fetch and mutate ${modelName} data
- */
-export function ${hookName}(options: Use${modelName}Options = {}) {
-  const queryClient = useQueryClient();
-  const { id, list, filters } = options;
-
-  // Fetch single ${modelName}
-  const { data: ${modelName.toLowerCase()}, isLoading: singleLoading, error: singleError } = useQuery({
-    queryKey: ['${modelName.toLowerCase()}', id],
-    queryFn: async () => {
-      if (!id) return null;
-      return await executeOperation('${controllerName}', 'retrieve', { id });
-    },
-    enabled: !!id && !list,
-  });
-
-  // Fetch list of ${modelName}s
-  const { data: ${modelName.toLowerCase()}s, isLoading: listLoading, error: listError } = useQuery({
-    queryKey: ['${modelName.toLowerCase()}s', filters],
-    queryFn: async () => {
-      return await executeOperation('${controllerName}', 'list', filters || {});
-    },
-    enabled: list,
-  });
-
-  const isLoading = list ? listLoading : singleLoading;
-  const error = list ? listError : singleError;
-
-  // Create mutation
-  const createMutation = useMutation({
-    mutationFn: async (data: Partial<${modelName}>) => {
-      return await executeOperation('${controllerName}', 'create', data);
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}s'] });
-    },
-  });
-
-  // Update mutation
-  const updateMutation = useMutation({
-    mutationFn: async ({ id, data }: { id: string; data: Partial<${modelName}> }) => {
-      return await executeOperation('${controllerName}', 'update', { id, ...data });
-    },
-    onSuccess: (_, variables) => {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}', variables.id] });
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}s'] });
-    },
-  });
-
-  // Delete mutation
-  const deleteMutation = useMutation({
-    mutationFn: async (id: string) => {
-      return await executeOperation('${controllerName}', 'delete', { id });
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}s'] });
-    },
-  });
-
-  // Refetch functions
-  const refetch = () => {
-    if (list) {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}s'] });
-    } else if (id) {
-      queryClient.invalidateQueries({ queryKey: ['${modelName.toLowerCase()}', id] });
+export function ${hookName}(opts: ${capitalize(hookName)}Options = {}) {
+  const { id, filters: _filters } = opts;
+
+  // Canonical list query — one cache key per model. The list flag
+  // is preserved for backwards compatibility but the query always
+  // runs; React Query dedupes across consumers automatically.
+  const query = useEntitiesQuery('${controllerName}', '${modelName}');
+  const ${plural} = (query.data as ${modelName}[] | undefined) || [];
+
+  // Single-entity lookup is client-side against the canonical list
+  // so both the detail view and the list view share one source of
+  // truth. If the caller needs server-side hydration for a single
+  // entity, they should call useEntitiesQuery directly with a
+  // filtered controller endpoint.
+  const ${singular} = useMemo<${modelName} | null>(() => {
+    if (!id) return null;
+    for (const entity of ${plural}) {
+      const entityId = (entity as any)?.id || (entity as any)?.data?.id;
+      if (entityId === id) return entity;
     }
-  };
+    return null;
+  }, [id, ${plural}]);
+
+  const mutation = useExecuteOperationMutation();
 
   return {
-    ${modelName.toLowerCase()},
-    ${modelName.toLowerCase()}s,
-    isLoading,
-    error,
-    refetch,
-    create: createMutation.mutateAsync,
-    update: updateMutation.mutateAsync,
-    delete: deleteMutation.mutateAsync,
-    isCreating: createMutation.isPending,
-    isUpdating: updateMutation.isPending,
-    isDeleting: deleteMutation.isPending,
+    ${singular},
+    ${plural},
+    isLoading: query.isLoading,
+    error: query.error,
+    refetch: () => { /* handled by useEntitiesQuery refetchInterval + WS invalidation */ },
+    create: (data: Partial<${modelName}>) =>
+      mutation.mutateAsync({ controllerName: '${controllerName}', operationName: 'create', data: data as Record<string, unknown> }),
+    update: (args: { id: string; data: Partial<${modelName}> }) =>
+      mutation.mutateAsync({ controllerName: '${controllerName}', operationName: 'update', entityId: args.id, data: args.data as Record<string, unknown> }),
+    delete: (entityId: string) =>
+      mutation.mutateAsync({ controllerName: '${controllerName}', operationName: 'delete', entityId, data: {} }),
+    isCreating: mutation.isPending,
+    isUpdating: mutation.isPending,
+    isDeleting: mutation.isPending,
   };
 }
 `;
 }
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specverse/engines",
-  "version": "4.1.22",
+  "version": "4.1.23",
   "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry",
   "type": "module",
   "main": "dist/index.js",