@specverse/engines 4.1.21 → 4.1.22

package/dist/libs/instance-factories/applications/templates/react/api-client-generator.js

@@ -304,6 +304,22 @@ export async function executeOperation(
   return apiRequest<ApiResponse>(method, path, Object.keys(params).length > 0 ? params : null);
 }
 
+/**
+ * Execute a service operation
+ * Services are RPC-style under /services/{serviceName}/{operationName}
+ */
+export async function executeServiceOperation(
+  serviceName: string,
+  operationName: string,
+  params: Record<string, any>
+): Promise<ApiResponse> {
+  return apiRequest<ApiResponse>(
+    'POST',
+    \`/services/\${serviceName}/\${operationName}\`,
+    params
+  );
+}
+
 /**
  * Transition entity lifecycle state
  */
@@ -395,6 +411,22 @@ export async function executeOperation(
   );
 }
 
+/**
+ * Execute a service operation
+ * Services are RPC-style under /services/{serviceName}/{operationName}
+ */
+export async function executeServiceOperation(
+  serviceName: string,
+  operationName: string,
+  params: Record<string, any>
+): Promise<ApiResponse> {
+  return apiRequest<ApiResponse>(
+    'POST',
+    \`/services/\${serviceName}/\${operationName}\`,
+    params
+  );
+}
+
 /**
  * Transition entity lifecycle state
  */

package/dist/libs/instance-factories/applications/templates/react/runtime-app-tsx-generator.js

@@ -1,10 +1,10 @@
 function generateRuntimeAppTsx(context) {
   const { spec } = context;
   const appName = spec?.metadata?.name || spec?.name || "SpecVerse App";
-  return `import { useState, useEffect, useMemo } from 'react';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+  return `import { useState, useEffect, useMemo, useCallback } from 'react';
+import { QueryClient, QueryClientProvider, useQueryClient } from '@tanstack/react-query';
 import yaml from 'js-yaml';
-import { RuntimeViewProvider } from '@specverse/runtime/views/react';
+import { RuntimeViewProvider, useEntitySync } from '@specverse/runtime/views/react';
 import { DevShell } from '@specverse/runtime/views/react';
 import {
   useEntitiesQuery,
@@ -12,6 +12,7 @@ import {
   useExecuteOperationMutation,
   useTransitionStateMutation,
 } from './hooks/useApi';
+import { listEntities, getRuntimeInfo } from './lib/apiClient';
 import devSpecRaw from './dev.specly?raw';
 
 // Parse YAML spec
@@ -64,6 +65,40 @@ function AppContent() {
       .catch(() => {});
   }, []);
 
+  // State-sync contract: WebSocket entity events \u2192 React Query cache
+  // invalidation. This is what guarantees "delete in one view is visible
+  // in every other view within one WS round-trip" \u2014 it runs at the App
+  // level so it's always on, regardless of which tab is active.
+  const queryClient = useQueryClient();
+  const invalidateEntities = useCallback((modelName: string) => {
+    queryClient.invalidateQueries({ queryKey: ['entities', modelName] });
+  }, [queryClient]);
+  useEntitySync({ invalidateEntities, apiBaseUrl: '/api' });
+
+  // Name resolver for OperationResultView. Kept in the host so runtime
+  // view components never issue raw fetch() calls \u2014 all HTTP goes
+  // through apiClient's canonical layer.
+  const resolveEntityNames = useCallback(async (ids: string[]): Promise<Record<string, string>> => {
+    const names: Record<string, string> = {};
+    try {
+      const info = await getRuntimeInfo();
+      const models = info?.models || [];
+      await Promise.all(models.map(async (model: string) => {
+        try {
+          const entities = await listEntities(model + 'Controller');
+          for (const entity of entities) {
+            const id = (entity as any)?.id;
+            const dataId = (entity as any)?.data?.id;
+            const display = (entity as any)?.name || (entity as any)?.title || (entity as any)?.label || id;
+            if (id && ids.includes(id)) names[id] = String(display);
+            if (dataId && ids.includes(dataId)) names[dataId] = String(display);
+          }
+        } catch { /* skip this model */ }
+      }));
+    } catch { /* ignore \u2014 caller falls back to raw IDs */ }
+    return names;
+  }, []);
+
   const runtimeValue = useMemo(() => ({
     useEntitiesQuery,
     useModelSchemaQuery,
@@ -74,7 +109,9 @@ function AppContent() {
     views: [],
     spec: appSpec,
     apiBaseUrl: '/api',
-  }), [appSpec]);
+    invalidateEntities,
+    resolveEntityNames,
+  }), [appSpec, invalidateEntities, resolveEntityNames]);
 
   return (
     <RuntimeViewProvider value={runtimeValue}>

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

@@ -11,6 +11,7 @@ import {
   getModelSchema,
   listEntities,
   executeOperation,
+  executeServiceOperation,
   transitionState
 } from '../lib/apiClient';
 import type { ModelSchema, Entity, ApiResponse } from '../types/api';
@@ -49,9 +50,14 @@ export function useEntitiesQuery(controllerName: string | null, modelName: strin
 }
 
 /**
- * Mutation hook for executing operations
- * Matches RuntimeViewProviderValue.useExecuteOperationMutation contract:
- *   { controllerName, operationName, data, entityId? }
+ * Mutation hook for executing operations \u2014 handles both controllers
+ * and services. Pass either \`controllerName\` (for CRUD or custom
+ * controller actions) or \`serviceName\` (for RPC-style service ops).
+ *
+ * Matches RuntimeViewProviderValue.useExecuteOperationMutation contract.
+ * Service operations invalidate the \`services\` query key; controller
+ * operations invalidate the corresponding model's \`entities\` key so
+ * all mounted views refetch automatically.
  */
 export function useExecuteOperationMutation() {
   const queryClient = useQueryClient();
@@ -59,12 +65,14 @@ export function useExecuteOperationMutation() {
   return useMutation({
     mutationFn: ({
       controllerName,
+      serviceName,
       operationName,
       data,
       params,
       entityId
     }: {
-      controllerName: string;
+      controllerName?: string;
+      serviceName?: string;
       operationName: string;
       data?: Record<string, any>;
       params?: Record<string, any>;
@@ -73,11 +81,23 @@ export function useExecuteOperationMutation() {
       // Merge: accept both 'data' and 'params' for compatibility
       const mergedParams = { ...(data || params || {}) };
       if (entityId) mergedParams.id = entityId;
-      return executeOperation(controllerName, operationName, mergedParams);
+      if (serviceName) {
+        return executeServiceOperation(serviceName, operationName, mergedParams);
+      }
+      if (controllerName) {
+        return executeOperation(controllerName, operationName, mergedParams);
+      }
+      throw new Error('useExecuteOperationMutation: either controllerName or serviceName is required');
     },
     onSuccess: (_data, variables) => {
-      const modelName = variables.controllerName.replace(/Controller$/, '');
-      queryClient.invalidateQueries({ queryKey: ['entities', modelName] });
+      if (variables.controllerName) {
+        const modelName = variables.controllerName.replace(/Controller$/, '');
+        queryClient.invalidateQueries({ queryKey: ['entities', modelName] });
+      }
+      // Service operations aren't tied to a single entity type; no
+      // cache key to invalidate here. If a service mutation affects
+      // entities, the backend should publish an event that
+      // useEntitySync picks up via WebSocket.
     }
   });
 }

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

@@ -340,6 +340,22 @@ export async function executeOperation(
   return apiRequest<ApiResponse>(method, path, Object.keys(params).length > 0 ? params : null);
 }
 
+/**
+ * Execute a service operation
+ * Services are RPC-style under /services/{serviceName}/{operationName}
+ */
+export async function executeServiceOperation(
+  serviceName: string,
+  operationName: string,
+  params: Record<string, any>
+): Promise<ApiResponse> {
+  return apiRequest<ApiResponse>(
+    'POST',
+    \`/services/\${serviceName}/\${operationName}\`,
+    params
+  );
+}
+
 /**
  * Transition entity lifecycle state
  */
@@ -432,6 +448,22 @@ export async function executeOperation(
   );
 }
 
+/**
+ * Execute a service operation
+ * Services are RPC-style under /services/{serviceName}/{operationName}
+ */
+export async function executeServiceOperation(
+  serviceName: string,
+  operationName: string,
+  params: Record<string, any>
+): Promise<ApiResponse> {
+  return apiRequest<ApiResponse>(
+    'POST',
+    \`/services/\${serviceName}/\${operationName}\`,
+    params
+  );
+}
+
 /**
  * Transition entity lifecycle state
  */

package/libs/instance-factories/applications/templates/react/runtime-app-tsx-generator.ts

@@ -13,10 +13,10 @@ export default function generateRuntimeAppTsx(context: TemplateContext): string
   const { spec } = context;
   const appName = (spec as any)?.metadata?.name || (spec as any)?.name || 'SpecVerse App';
 
-  return `import { useState, useEffect, useMemo } from 'react';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+  return `import { useState, useEffect, useMemo, useCallback } from 'react';
+import { QueryClient, QueryClientProvider, useQueryClient } from '@tanstack/react-query';
 import yaml from 'js-yaml';
-import { RuntimeViewProvider } from '@specverse/runtime/views/react';
+import { RuntimeViewProvider, useEntitySync } from '@specverse/runtime/views/react';
 import { DevShell } from '@specverse/runtime/views/react';
 import {
   useEntitiesQuery,
@@ -24,6 +24,7 @@ import {
   useExecuteOperationMutation,
   useTransitionStateMutation,
 } from './hooks/useApi';
+import { listEntities, getRuntimeInfo } from './lib/apiClient';
 import devSpecRaw from './dev.specly?raw';
 
 // Parse YAML spec
@@ -76,6 +77,40 @@ function AppContent() {
       .catch(() => {});
   }, []);
 
+  // State-sync contract: WebSocket entity events → React Query cache
+  // invalidation. This is what guarantees "delete in one view is visible
+  // in every other view within one WS round-trip" — it runs at the App
+  // level so it's always on, regardless of which tab is active.
+  const queryClient = useQueryClient();
+  const invalidateEntities = useCallback((modelName: string) => {
+    queryClient.invalidateQueries({ queryKey: ['entities', modelName] });
+  }, [queryClient]);
+  useEntitySync({ invalidateEntities, apiBaseUrl: '/api' });
+
+  // Name resolver for OperationResultView. Kept in the host so runtime
+  // view components never issue raw fetch() calls — all HTTP goes
+  // through apiClient's canonical layer.
+  const resolveEntityNames = useCallback(async (ids: string[]): Promise<Record<string, string>> => {
+    const names: Record<string, string> = {};
+    try {
+      const info = await getRuntimeInfo();
+      const models = info?.models || [];
+      await Promise.all(models.map(async (model: string) => {
+        try {
+          const entities = await listEntities(model + 'Controller');
+          for (const entity of entities) {
+            const id = (entity as any)?.id;
+            const dataId = (entity as any)?.data?.id;
+            const display = (entity as any)?.name || (entity as any)?.title || (entity as any)?.label || id;
+            if (id && ids.includes(id)) names[id] = String(display);
+            if (dataId && ids.includes(dataId)) names[dataId] = String(display);
+          }
+        } catch { /* skip this model */ }
+      }));
+    } catch { /* ignore — caller falls back to raw IDs */ }
+    return names;
+  }, []);
+
   const runtimeValue = useMemo(() => ({
     useEntitiesQuery,
     useModelSchemaQuery,
@@ -86,7 +121,9 @@ function AppContent() {
     views: [],
     spec: appSpec,
     apiBaseUrl: '/api',
-  }), [appSpec]);
+    invalidateEntities,
+    resolveEntityNames,
+  }), [appSpec, invalidateEntities, resolveEntityNames]);
 
   return (
     <RuntimeViewProvider value={runtimeValue}>

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

@@ -21,6 +21,7 @@ import {
   getModelSchema,
   listEntities,
   executeOperation,
+  executeServiceOperation,
   transitionState
 } from '../lib/apiClient';
 import type { ModelSchema, Entity, ApiResponse } from '../types/api';
@@ -59,9 +60,14 @@ export function useEntitiesQuery(controllerName: string | null, modelName: strin
 }
 
 /**
- * Mutation hook for executing operations
- * Matches RuntimeViewProviderValue.useExecuteOperationMutation contract:
- *   { controllerName, operationName, data, entityId? }
+ * Mutation hook for executing operations — handles both controllers
+ * and services. Pass either \`controllerName\` (for CRUD or custom
+ * controller actions) or \`serviceName\` (for RPC-style service ops).
+ *
+ * Matches RuntimeViewProviderValue.useExecuteOperationMutation contract.
+ * Service operations invalidate the \`services\` query key; controller
+ * operations invalidate the corresponding model's \`entities\` key so
+ * all mounted views refetch automatically.
  */
 export function useExecuteOperationMutation() {
   const queryClient = useQueryClient();
@@ -69,12 +75,14 @@ export function useExecuteOperationMutation() {
   return useMutation({
     mutationFn: ({
       controllerName,
+      serviceName,
       operationName,
       data,
       params,
       entityId
     }: {
-      controllerName: string;
+      controllerName?: string;
+      serviceName?: string;
       operationName: string;
       data?: Record<string, any>;
       params?: Record<string, any>;
@@ -83,11 +91,23 @@ export function useExecuteOperationMutation() {
       // Merge: accept both 'data' and 'params' for compatibility
       const mergedParams = { ...(data || params || {}) };
       if (entityId) mergedParams.id = entityId;
-      return executeOperation(controllerName, operationName, mergedParams);
+      if (serviceName) {
+        return executeServiceOperation(serviceName, operationName, mergedParams);
+      }
+      if (controllerName) {
+        return executeOperation(controllerName, operationName, mergedParams);
+      }
+      throw new Error('useExecuteOperationMutation: either controllerName or serviceName is required');
     },
     onSuccess: (_data, variables) => {
-      const modelName = variables.controllerName.replace(/Controller$/, '');
-      queryClient.invalidateQueries({ queryKey: ['entities', modelName] });
+      if (variables.controllerName) {
+        const modelName = variables.controllerName.replace(/Controller$/, '');
+        queryClient.invalidateQueries({ queryKey: ['entities', modelName] });
+      }
+      // Service operations aren't tied to a single entity type; no
+      // cache key to invalidate here. If a service mutation affects
+      // entities, the backend should publish an event that
+      // useEntitySync picks up via WebSocket.
     }
   });
 }

package/package.json

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