@specverse/engines 4.1.28 → 4.2.0

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

@@ -0,0 +1,137 @@
+/**
+ * View files generator for ReactAppStarter
+ *
+ * Called by the realize engine. Iterates over the expanded spec's
+ * models × view types, dispatches to the right composer, and returns
+ * a filename → source map. Realize writes each file.
+ *
+ * Also emits the local helpers library (src/lib/entity-display.ts)
+ * so generated projects have zero @specverse/runtime runtime deps.
+ */
+
+import { emitView, type EmitContext, type ModelSpec, type ViewSpec, type RenderBodyFn } from './view-emitter.js';
+import { composeListBody } from './list-body-composer.js';
+import { composeDetailBody } from './detail-body-composer.js';
+import { composeFormBody } from './form-body-composer.js';
+import { composeDashboardBody } from './dashboard-body-composer.js';
+import { emitEntityDisplay } from './helpers-emitter.js';
+
+/**
+ * The four primary view types Factory B currently emits. Specialist
+ * types (board, timeline, calendar, etc.) are not yet implemented —
+ * if the expanded spec declares one, we skip it and log a TODO.
+ * These users can add composers under Phase 2e.
+ */
+const PRIMARY_VIEW_TYPES = ['list', 'detail', 'form', 'dashboard'] as const;
+type PrimaryViewType = typeof PRIMARY_VIEW_TYPES[number];
+
+const COMPOSER_BY_TYPE: Record<PrimaryViewType, RenderBodyFn> = {
+  list: composeListBody,
+  detail: composeDetailBody,
+  form: composeFormBody,
+  dashboard: composeDashboardBody,
+};
+
+/** Generator contract — the shape realize expects. */
+export interface ViewsGeneratorContext {
+  /** The expanded spec (post-inference). */
+  spec: ExpandedSpec;
+  /** The resolved manifest configuration. Not currently read by this
+   *  generator but passed by realize for parity with other generators. */
+  manifest?: unknown;
+}
+
+export interface ExpandedSpec {
+  /** Models keyed by name. */
+  models?: Record<string, ModelSpec>;
+  /** Views keyed by view name (e.g. "PostListView"). */
+  views?: Record<string, ViewSpec & { type: string; model?: string }>;
+}
+
+export interface GeneratedFiles {
+  [relativePath: string]: string;
+}
+
+/**
+ * Generate all view files + local helpers.
+ *
+ * Paths are RELATIVE to the frontend root (`frontendDir` in the
+ * manifest). Realize prepends the absolute output path when writing.
+ */
+export async function generate(context: ViewsGeneratorContext): Promise<GeneratedFiles> {
+  const files: GeneratedFiles = {};
+  const spec = context.spec;
+  const models = spec.models ?? {};
+  const viewsBySpec = spec.views ?? {};
+
+  // Group the spec's views by model+type so we can decide, for each
+  // (model, type) pair, whether to use the user's view spec or emit
+  // a default.
+  const viewIndex = indexViews(viewsBySpec);
+  const skippedSpecialists: string[] = [];
+
+  for (const [modelName, model] of Object.entries(models)) {
+    for (const viewType of PRIMARY_VIEW_TYPES) {
+      const viewName = `${modelName}${capitalize(viewType)}View`;
+      // Prefer a user-defined view of that shape if one exists; fall
+      // back to a synthesized default.
+      const view = viewIndex.get(viewName) ?? synthesizeDefault(modelName, viewType);
+      const source = emitView({
+        view,
+        viewName,
+        model,
+        modelSchemas: models,
+        renderBody: COMPOSER_BY_TYPE[viewType],
+      });
+      files[`src/views/${viewName}.tsx`] = source;
+    }
+  }
+
+  // Surface any specialist-type views the user declared but we can't
+  // emit yet. The runtime (ReactAppRuntime) handles these; in starter
+  // kit mode the user has to write them manually for now.
+  for (const [name, view] of Object.entries(viewsBySpec)) {
+    if (!PRIMARY_VIEW_TYPES.includes(view.type as PrimaryViewType)) {
+      skippedSpecialists.push(`${name} (type=${view.type})`);
+    }
+  }
+  if (skippedSpecialists.length > 0) {
+    console.warn(
+      `[ReactAppStarter] Skipped ${skippedSpecialists.length} specialist view(s) — ` +
+      `implement composers for: ${[...new Set(Object.values(viewsBySpec)
+        .filter(v => !PRIMARY_VIEW_TYPES.includes(v.type as PrimaryViewType))
+        .map(v => v.type))].join(', ')}. ` +
+      `Skipped: ${skippedSpecialists.join(', ')}`
+    );
+  }
+
+  // Local helpers
+  files['src/lib/entity-display.ts'] = emitEntityDisplay();
+
+  return files;
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────────────────────
+
+function indexViews(
+  views: Record<string, ViewSpec & { type: string; model?: string }>
+): Map<string, ViewSpec & { type: string; model?: string }> {
+  const out = new Map<string, ViewSpec & { type: string; model?: string }>();
+  for (const [name, view] of Object.entries(views)) {
+    out.set(name, view);
+  }
+  return out;
+}
+
+function synthesizeDefault(modelName: string, viewType: PrimaryViewType): ViewSpec {
+  return {
+    type: viewType,
+    model: modelName,
+  };
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/libs/instance-factories/cli/templates/commander/command-generator.ts

@@ -393,22 +393,25 @@ import type { ParserEngine, InferenceEngine, RealizeEngine } from '@specverse/ty
           process.exit(1);
         }
 
-        // Runtime mode (default): swap ReactApp → ReactAppRuntime in manifest
+        // --static ejects to a standalone starter kit (ReactAppStarter).
+        // Default: whatever the manifest declares (ReactAppRuntime in the
+        // shipped templates). The swap is a convenience only — users can
+        // achieve the same by editing their manifest directly.
         let effectiveManifestPath = manifestPath;
-        if (!options.static) {
+        if (options.static) {
           const manifestContent = readFileSync(manifestPath, 'utf8');
-          if (/instanceFactory:\\s*["']?ReactApp["']?\\s*$/m.test(manifestContent)) {
+          if (/instanceFactory:\\s*["']?ReactAppRuntime["']?\\s*$/m.test(manifestContent)) {
             const { tmpdir } = await import('os');
-            const runtimeManifest = manifestContent.replace(
-              /instanceFactory:\\s*["']?ReactApp["']?\\s*$/gm,
-              'instanceFactory: "ReactAppRuntime"'
+            const staticManifest = manifestContent.replace(
+              /instanceFactory:\\s*["']?ReactAppRuntime["']?\\s*$/gm,
+              'instanceFactory: "ReactAppStarter"'
             );
-            effectiveManifestPath = join(tmpdir(), 'specverse-runtime-manifest.yaml');
-            writeFileSync(effectiveManifestPath, runtimeManifest, 'utf8');
-            console.log('  Using runtime mode (slim frontend with @specverse/runtime)');
+            effectiveManifestPath = join(tmpdir(), 'specverse-static-manifest.yaml');
+            writeFileSync(effectiveManifestPath, staticManifest, 'utf8');
+            console.log('  Using static mode (standalone starter kit — ReactAppStarter)');
+          } else {
+            console.log('  Using static mode (manifest factory unchanged)');
           }
-        } else {
-          console.log('  Using static mode (full frontend generation)');
         }
 
         const realizeEngine = registry.getEngineForCapability('realize') as RealizeEngine;

package/libs/instance-factories/controllers/templates/fastify/server-generator.ts

@@ -82,8 +82,11 @@ fastify.get('/api/runtime/info', async () => ({
   services: ${JSON.stringify(servicesList)}
 }));
 
-${hasEvents ? `// Event history endpoint
-fastify.get('/api/events', async () => eventBus.getHistory());` : ''}
+${hasEvents ? `// Event history endpoint — runtime introspection, not part of
+// the user's API surface. Lives under /api/runtime/ so it doesn't
+// collide with the auto-generated Event model route (spec models
+// named "Event" produce a GET /api/events of their own).
+fastify.get('/api/runtime/events', async () => eventBus.getHistory());` : ''}
 
 // Register routes
 ${routeImports}
@@ -102,7 +105,12 @@ const start = async () => {
 ${hasEvents ? `    // Register WebSocket bridge for real-time frontend events
     await registerWebSocketBridge(fastify);` : ''}
     const port = parseInt(process.env.PORT || '3000');
-    await fastify.listen({ port, host: '0.0.0.0' });
+    // Listen on :: (IPv6 wildcard) instead of 0.0.0.0 so the server
+    // accepts both IPv6 and IPv4-mapped connections. Node resolves
+    // 'localhost' to ::1 first; if the backend only binds IPv4, the
+    // vite dev-server WS proxy hits ECONNREFUSED on ::1 and doesn't
+    // fall back to 127.0.0.1 cleanly. Binding :: fixes both cases.
+    await fastify.listen({ port, host: '::' });
     console.log(\`Server running at http://localhost:\${port}\`);
     console.log(\`API endpoints: ${modelNames.map((n: string) => `/api/${n.toLowerCase()}s`).join(', ')}\`);
 ${hasEvents ? `    console.log(\`WebSocket: ws://localhost:\${port}/ws\`);

package/libs/instance-factories/services/templates/prisma/controller-generator.ts

@@ -282,39 +282,49 @@ function generateEvolveMethod(model: any, modelName: string, modelVar: string, p
 
   return `
   /**
-   * Evolve ${modelName} through lifecycle
+   * Evolve ${modelName} through lifecycle "${lifecycleName}"
    * States: ${states.join(' → ')}
+   *
+   * Accepts either the client shape { toState, lifecycleName? } or
+   * the direct column shape { ${lifecycleName}: ... }. The frontend
+   * runtime's useTransitionStateMutation always sends the former; the
+   * realized smoke-parity script can send either.
    */
   public async evolve(id: string, data: any): Promise<any> {
-    // Validate input
-    const validationResult = this.validate(data, { operation: 'evolve' });
-    if (!validationResult.valid) {
-      throw new Error(\`Validation failed: \${validationResult.errors.join(', ')}\`);
-    }
-
     // Get current record to check lifecycle state
     const current = await ${prismaDelegate}.findUnique({ where: { id: parseId(id) } });
     if (!current) {
       throw new Error('${modelName} not found');
     }
 
+    // Normalize input: translate client { toState: X } shape to the
+    // lifecycle's actual column name. If the caller already sent the
+    // column directly, keep whatever they sent.
+    const targetLifecycle = data?.lifecycleName || '${lifecycleName}';
+    const targetState = data?.toState ?? data?.state ?? data?.[targetLifecycle];
+    if (!targetState) {
+      throw new Error('evolve requires toState (or ${lifecycleName}) in the request body');
+    }
+
     ${states.length > 0 ? `
-    // Validate lifecycle transition
-    const currentState = (current as any).${lifecycleName};
-    const newState = data.${lifecycleName};
-    if (newState) {
-      const validTransitions: Record<string, string[]> = ${JSON.stringify(validTransitions)};
-      const allowed = validTransitions[currentState] || [];
-      if (!allowed.includes(newState)) {
-        throw new Error(\`Invalid transition: \${currentState} → \${newState}. Allowed: \${allowed.join(', ') || 'none'}\`);
-      }
+    // Validate lifecycle transition against declared flow
+    const currentState = (current as any)[targetLifecycle];
+    const validTransitions: Record<string, string[]> = ${JSON.stringify(validTransitions)};
+    const allowed = validTransitions[currentState] || [];
+    if (!allowed.includes(targetState)) {
+      throw new Error(\`Invalid transition: \${currentState} → \${targetState}. Allowed: \${allowed.join(', ') || 'none'}\`);
     }
     ` : ''}
 
+    // Build the Prisma update payload — only the lifecycle column
+    // changes. Strips toState/lifecycleName/state so Prisma doesn't
+    // reject unknown fields.
+    const updateData: any = { [targetLifecycle]: targetState };
+
     // Update record
     const ${modelVar} = await ${prismaDelegate}.update({
       where: { id: parseId(id) },
-      data${generateIncludeRelationships(model)}
+      data: updateData${generateIncludeRelationships(model)}
     });
 
     // Publish CURED event

package/libs/instance-factories/shared/path-resolver.ts

@@ -93,9 +93,15 @@ export function getApiBaseUrl(config: PathResolverConfig & { apiBaseUrl?: string
     return '${VITE_API_BASE_URL}'; // Environment variable placeholder
   }
 
-  // In monorepo mode, default to local backend
+  // In monorepo mode, default to local backend.
+  // Use explicit 127.0.0.1 (not `localhost`) to avoid Node's
+  // happy-eyeballs IPv6→IPv4 fallback. The vite dev-server WS proxy
+  // doesn't handle that fallback for WebSocket upgrades — it would
+  // try `[::1]:3000`, get ECONNREFUSED if the backend isn't on IPv6,
+  // and log the error instead of retrying on 127.0.0.1. Pinning
+  // 127.0.0.1 in the proxy target sidesteps that entirely.
   const port = (config as any).serverPort || 3000;
-  return `http://localhost:${port}`;
+  return `http://127.0.0.1:${port}`;
 }
 
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@specverse/engines",
-  "version": "4.1.28",
-  "description": "SpecVerse toolchain \u2014 parser, inference, realize, generators, AI, registry",
+  "version": "4.2.0",
+  "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -65,4 +65,4 @@
     "access": "public"
   },
   "license": "MIT"
-}
+}