@specverse/engines 4.2.0 → 4.2.2

package/libs/instance-factories/applications/templates/react-starter/list-body-composer.ts

@@ -21,6 +21,7 @@ import { createUniversalTailwindAdapter } from '@specverse/runtime/views/tailwin
 import { inferFieldsFromSchema } from '@specverse/runtime/views/core';
 import { htmlToJsx } from './html-to-jsx.js';
 import type { EmitContext, ModelSpec } from './view-emitter.js';
+import { buildFKMap } from './belongs-to.js';
 
 /**
  * Sentinel token. Must be ASCII-safe (no curly braces) so it survives
@@ -34,8 +35,24 @@ const TBODY_SENTINEL = '__SPECVERSE_TBODY_ROWS__';
  * meant to be dropped at `{{BODY}}` inside `skeletons/list.tsx.template`.
  */
 export function composeListBody(context: EmitContext): string {
-  const columns = inferColumns(context);
-  const headers = columns.map(humanize);
+  const fkMap = buildFKMap(context.model);
+  // Inference (`inferFieldsFromSchema`) reads attributes and doesn't
+  // see belongsTo relationships. For list views we want a column per
+  // belongsTo so users can scan "who owns this" at a glance —
+  // otherwise a Task table hides its Project and Assignee columns.
+  // Append any FK columns the inference missed, preserving order.
+  const inferred = inferColumns(context);
+  const inferredSet = new Set(inferred);
+  const extraFKs = [...fkMap.keys()].filter(k => !inferredSet.has(k));
+  const columns = [...inferred, ...extraFKs];
+
+  // Header label for an FK column should use the relationship name
+  // ("Owner") not the raw column name ("Owner Id"). The cell rendering
+  // in buildRowMap applies the matching FK→name resolution.
+  const headers = columns.map(col => {
+    const fk = fkMap.get(col);
+    return humanize(fk ? fk.name : col);
+  });
 
   const adapter = createUniversalTailwindAdapter({ darkMode: true });
   const shellHtml = adapter.components.table.render({
@@ -52,7 +69,7 @@ export function composeListBody(context: EmitContext): string {
   // skeleton's useMemo produces `filtered: Model[]`, so the map
   // expression binds over that. onSelect is a prop the skeleton
   // declares. Delete action wires to the deleteItem mutation.
-  const rowMap = buildRowMap(columns);
+  const rowMap = buildRowMap(columns, fkMap);
 
   if (!shellJsx.includes(TBODY_SENTINEL)) {
     // Defensive: catches adapter output changes that no longer flow
@@ -93,17 +110,26 @@ function humanize(name: string): string {
  * row. Keep the output readable so users inspecting the generated
  * file can follow what's happening.
  */
-function buildRowMap(columns: string[]): string {
+function buildRowMap(columns: string[], fkMap: Map<string, { name: string; target: string }>): string {
   // Type-cast to `any` to avoid TS generic syntax (`<string, unknown>`)
   // inside JSX expressions, which the TSX parser can't always
   // disambiguate from a JSX opening tag. `any` is the right choice for
   // starter-kit output anyway — the user will often reshape the row
   // type after editing.
+  //
+  // FK columns render through `resolveEntityDisplayName(id, options)`
+  // so the user sees a name instead of a UUID. The options array
+  // (`${relName}Options`) is populated by the hook call wired into
+  // the list skeleton via view-emitter's RELATED_HOOKS substitution.
   const cells = columns
-    .map(col =>
-      `            <td className="px-6 py-4 text-sm text-gray-700 dark:text-gray-300">` +
-      `{String((item as any).${col} ?? '')}</td>`
-    )
+    .map(col => {
+      const fk = fkMap.get(col);
+      const expr = fk
+        ? `{resolveEntityDisplayName((item as any).${col}, ${fk.name}Options)}`
+        : `{String((item as any).${col} ?? '')}`;
+      return `            <td className="px-6 py-4 text-sm text-gray-700 dark:text-gray-300">` +
+        `${expr}</td>`;
+    })
     .join('\n');
 
   return [

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

@@ -13,6 +13,8 @@
  * so it rolls through the same write pipeline.
  */
 
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
 import { generate as generateViews } from './views-generator.js';
 import { generate as generateAppTsx } from './app-tsx-generator.js';
 import { generate as generatePackageJson } from './package-json-generator.js';
@@ -25,32 +27,35 @@ import {
 } from './regen-safety.js';
 import type { ExpandedSpec } from './views-generator.js';
 
+/**
+ * Context shape as it arrives from realize's code-generator. The
+ * generator protocol is "function receives context, returns string
+ * (the single file contents)". This orchestrator is special: instead
+ * of one file, it produces many (views × models, App.tsx,
+ * package.json, regen-safety manifest). It writes them directly and
+ * returns '' so realize's write pipeline skips the no-op.
+ *
+ * `outputDir` and `frontendDir` come from the realize-time context.
+ * `frontendDir` may be '.' for standalone layouts or 'frontend' for
+ * monorepos — either way, the resolved write root is
+ * `outputDir + frontendDir`.
+ */
 export interface OrchestratorContext {
-  /** Expanded spec (post-inference). */
   spec: ExpandedSpec & { metadata?: { name?: string }; name?: string };
-  /** Resolved manifest configuration. */
+  outputDir: string;
+  frontendDir?: string;
   manifest?: unknown;
-  /** Absolute path to the project root (the frontend directory for this factory). */
-  projectRoot: string;
 }
 
 /**
- * The shape realize expects from a multi-file generator: a map of
- * relative paths to their contents. Realize creates parent dirs and
- * writes the files verbatim.
- *
- * Skipped (user-edited) files are intentionally absent — realize
- * never sees them.
+ * Produce the complete file set for a Factory B run, writing each
+ * file directly. Returns '' so the caller's single-file writeOutput
+ * short-circuits.
  */
-export type OrchestratorOutput = Record<string, string>;
-
-/**
- * Produce the complete file set for a Factory B run. Realize writes
- * whatever comes back; the orchestrator is the sole source of truth
- * for "what ends up on disk."
- */
-export async function generate(context: OrchestratorContext): Promise<OrchestratorOutput> {
-  const { spec, projectRoot } = context;
+export async function generate(context: OrchestratorContext): Promise<string> {
+  const { spec, outputDir } = context;
+  const frontendDir = context.frontendDir || 'frontend';
+  const projectRoot = frontendDir === '.' ? outputDir : join(outputDir, frontendDir);
 
   // 1. Produce all file contents (pure composition — no I/O yet).
   const proposed: Record<string, string> = {};
@@ -61,20 +66,30 @@ export async function generate(context: OrchestratorContext): Promise<Orchestrat
   proposed['src/App.tsx'] = await generateAppTsx({ spec });
   proposed['package.json'] = await generatePackageJson({ spec });
 
-  // 2. Load prior hash manifest + triage. Read-only.
+  // 2. Content-hashing triage against the prior manifest. Read-only.
   const prevManifest = loadHashManifest(projectRoot);
   const result = reconcileWrites(projectRoot, proposed, prevManifest);
 
   // 3. Log the summary for operator visibility.
   console.log(summarize(result, projectRoot));
 
-  // 4. Emit the hash manifest as one of the written files so it flows
-  //    through realize's normal write pipeline.
-  const manifestPath = `${HASHES_DIR}/${HASHES_FILE}`;
-  const out: OrchestratorOutput = {
+  // 4. Write the approved files + the updated hash manifest.
+  const toWrite: Record<string, string> = {
     ...result.approvedWrites,
-    [manifestPath]: JSON.stringify(result.manifest, null, 2) + '\n',
+    [`${HASHES_DIR}/${HASHES_FILE}`]: JSON.stringify(result.manifest, null, 2) + '\n',
   };
 
-  return out;
+  for (const [rel, content] of Object.entries(toWrite)) {
+    const abs = join(projectRoot, rel);
+    const dir = dirname(abs);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(abs, content, 'utf-8');
+  }
+
+  // Realize's single-file writeOutput skips empty strings (see
+  // realize/index.ts writeOutput). The orchestrator already wrote
+  // everything it needed.
+  return '';
 }
+
+export default generate;

package/libs/instance-factories/applications/templates/react-starter/skeletons/dashboard.tsx.template

@@ -12,6 +12,7 @@
  */
 import { useMemo } from 'react';
 import { use{{PLURAL_MODEL}}Query } from '../hooks/useApi';
+{{RELATED_IMPORTS}}
 import type { {{MODEL_NAME}} } from '../types/api';
 
 interface {{MODEL_NAME}}DashboardViewProps {
@@ -25,6 +26,7 @@ export function {{MODEL_NAME}}DashboardView({
   onSelect,
 }: {{MODEL_NAME}}DashboardViewProps) {
   const { data: items = [], isLoading, error } = use{{PLURAL_MODEL}}Query();
+{{RELATED_HOOKS}}
 
   const preview = useMemo(
     () => items.slice(0, previewLimit),

package/libs/instance-factories/applications/templates/react-starter/skeletons/detail.tsx.template

@@ -6,6 +6,7 @@
  * regeneration of this file, delete it first, then run `spv realize`.
  */
 import { use{{PLURAL_MODEL}}Query, useDelete{{MODEL_NAME}}Mutation } from '../hooks/useApi';
+{{RELATED_IMPORTS}}
 import type { {{MODEL_NAME}} } from '../types/api';
 
 interface {{MODEL_NAME}}DetailViewProps {
@@ -24,6 +25,7 @@ export function {{MODEL_NAME}}DetailView({
 }: {{MODEL_NAME}}DetailViewProps) {
   const { data: items = [], isLoading, error } = use{{PLURAL_MODEL}}Query();
   const deleteItem = useDelete{{MODEL_NAME}}Mutation();
+{{RELATED_HOOKS}}
 
   const item = items.find(
     (x: {{MODEL_NAME}}) => (x as any).id === entityId

package/libs/instance-factories/applications/templates/react-starter/skeletons/form.tsx.template

@@ -14,6 +14,7 @@ import {
   useCreate{{MODEL_NAME}}Mutation,
   useUpdate{{MODEL_NAME}}Mutation,
 } from '../hooks/useApi';
+{{RELATED_IMPORTS}}
 import type { {{MODEL_NAME}} } from '../types/api';
 
 type FormMode = 'create' | 'update';
@@ -35,6 +36,7 @@ export function {{MODEL_NAME}}FormView({
   const { data: items = [] } = use{{PLURAL_MODEL}}Query();
   const createItem = useCreate{{MODEL_NAME}}Mutation();
   const updateItem = useUpdate{{MODEL_NAME}}Mutation();
+{{RELATED_HOOKS}}
 
   const existing =
     mode === 'update'

package/libs/instance-factories/applications/templates/react-starter/skeletons/list.tsx.template

@@ -7,6 +7,7 @@
  */
 import { useState, useMemo } from 'react';
 import { use{{PLURAL_MODEL}}Query, useDelete{{MODEL_NAME}}Mutation } from '../hooks/useApi';
+{{RELATED_IMPORTS}}
 import type { {{MODEL_NAME}} } from '../types/api';
 
 interface {{MODEL_NAME}}ListViewProps {
@@ -17,6 +18,7 @@ interface {{MODEL_NAME}}ListViewProps {
 export function {{MODEL_NAME}}ListView({ onSelect, onCreate }: {{MODEL_NAME}}ListViewProps) {
   const { data: items = [], isLoading, error } = use{{PLURAL_MODEL}}Query();
   const deleteItem = useDelete{{MODEL_NAME}}Mutation();
+{{RELATED_HOOKS}}
   const [searchTerm, setSearchTerm] = useState('');
 
   const filtered = useMemo(

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

@@ -0,0 +1,124 @@
+/**
+ * useApi hooks generator for ReactAppStarter
+ *
+ * Emits typed per-model React Query hooks that the starter's view
+ * skeletons import directly (`useTasksQuery`, `useCreateTaskMutation`,
+ * etc.). All hooks hit the realized backend's REST endpoints under
+ * `/api/{resource}` via the sibling `apiClient` helper.
+ *
+ * Why a separate generator from the runtime one: ReactAppRuntime
+ * ships a generic `useEntitiesQuery(controller, model)` because its
+ * views are rendered by @specverse/runtime using runtime dispatch.
+ * The starter wants plain typed hooks the user can read and edit.
+ */
+
+/**
+ * Minimal English pluralizer. Matches the conventions used by
+ * view-emitter so the generated hooks pair cleanly with the generated
+ * view imports.
+ */
+function pluralize(s: string): string {
+  if (/y$/.test(s) && !/[aeiou]y$/.test(s)) return s.replace(/y$/, 'ies');
+  if (/(s|x|z|ch|sh)$/.test(s)) return s + 'es';
+  return s + 's';
+}
+
+export interface UseApiHooksStarterContext {
+  spec: {
+    models?: Record<string, any>;
+  };
+  manifest?: unknown;
+}
+
+export async function generate(context: UseApiHooksStarterContext): Promise<string> {
+  const models = Object.keys(context.spec.models ?? {});
+
+  const importsAndTypes = `/**
+ * useApi — typed per-model React Query hooks (ReactAppStarter)
+ *
+ * Safe to edit. Users who want to reshape their API client or add
+ * request/response interceptors should start here. Each hook calls
+ * the sibling \`apiClient\` which does the actual fetch; edit
+ * \`apiClient.ts\` to change transport concerns (headers, auth, etc.).
+ */
+
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+${models.map(m => `import type { ${m} } from '../types/api';`).join('\n')}
+
+const API_BASE = import.meta.env.VITE_API_BASE_URL || '';
+
+async function fetchJSON<T = unknown>(url: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(url, {
+    headers: { 'Content-Type': 'application/json' },
+    ...init,
+  });
+  if (!res.ok) {
+    throw new Error(\`\${res.status} \${res.statusText} — \${url}\`);
+  }
+  if (res.status === 204) return undefined as T;
+  return (await res.json()) as T;
+}
+`;
+
+  const hookBlocks = models.map(m => generateModelHooks(m)).join('\n\n');
+
+  return importsAndTypes + '\n' + hookBlocks + '\n';
+}
+
+function generateModelHooks(model: string): string {
+  const plural = pluralize(model);
+  const resource = plural.toLowerCase();
+  const modelLower = model.toLowerCase();
+
+  return `// ─── ${model} ───────────────────────────────────────────────────
+
+export function use${plural}Query() {
+  return useQuery({
+    queryKey: ['${resource}'],
+    queryFn: () => fetchJSON<${model}[]>(\`\${API_BASE}/api/${resource}\`),
+  });
+}
+
+export function use${model}Query(id: string | number | undefined) {
+  return useQuery({
+    queryKey: ['${resource}', id],
+    queryFn: () => fetchJSON<${model}>(\`\${API_BASE}/api/${resource}/\${id}\`),
+    enabled: id !== undefined && id !== null,
+  });
+}
+
+export function useCreate${model}Mutation() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (data: Partial<${model}>) =>
+      fetchJSON<${model}>(\`\${API_BASE}/api/${resource}\`, {
+        method: 'POST',
+        body: JSON.stringify(data),
+      }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['${resource}'] }),
+  });
+}
+
+export function useUpdate${model}Mutation() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string | number; data: Partial<${model}> }) =>
+      fetchJSON<${model}>(\`\${API_BASE}/api/${resource}/\${id}\`, {
+        method: 'PATCH',
+        body: JSON.stringify(data),
+      }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['${resource}'] }),
+  });
+}
+
+export function useDelete${model}Mutation() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (id: string | number) =>
+      fetchJSON<void>(\`\${API_BASE}/api/${resource}/\${id}\`, { method: 'DELETE' }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['${resource}'] }),
+  });
+}`;
+}
+
+export default generate;

package/libs/instance-factories/applications/templates/react-starter/view-emitter.ts

@@ -16,6 +16,7 @@
 import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { extractBelongsToTargets, pluralize as pluralizeShared } from './belongs-to.js';
 
 /**
  * The minimal shape of a view spec this emitter needs. Matches the
@@ -113,17 +114,74 @@ interface Substitutions {
   PLURAL_LOWER: string;
   SINGULAR_LOWER: string;
   BODY: string;
+  /**
+   * For form views: extra import lines that pull in the hooks and
+   * display-name helper needed to render belongsTo <select>s. Empty
+   * string for views / models with no belongsTo relationships.
+   */
+  RELATED_IMPORTS: string;
+  /**
+   * For form views: extra hook calls inside the component body —
+   * one per belongsTo target — that populate the `${relName}Options`
+   * array each <select> iterates. Empty string when there are none.
+   */
+  RELATED_HOOKS: string;
 }
 
 function buildSubstitutions(context: EmitContext, body: string): Substitutions {
   const modelName = context.model.name;
   const pluralModel = pluralize(modelName);
+  const { imports, hooks } = buildBelongsToWiring(context);
   return {
     MODEL_NAME: modelName,
     PLURAL_MODEL: pluralModel,
     PLURAL_LOWER: pluralModel.toLowerCase(),
     SINGULAR_LOWER: modelName.toLowerCase(),
     BODY: body,
+    RELATED_IMPORTS: imports,
+    RELATED_HOOKS: hooks,
+  };
+}
+
+/**
+ * Compute the belongsTo wiring for a view: one import line per unique
+ * target hook, one hook call per relationship (even if two relations
+ * share a target — each needs its own options variable).
+ *
+ * The entity-display helper import set is view-type-dependent to
+ * avoid unused-import TS errors:
+ *   - form uses `getEntityDisplayName(opt)` (has whole entity in hand)
+ *   - list / detail / dashboard use `resolveEntityDisplayName(id, list)`
+ *     (has FK id, looks up in the list)
+ */
+function buildBelongsToWiring(context: EmitContext): { imports: string; hooks: string } {
+  const rels = extractBelongsToTargets(context.model);
+  if (rels.length === 0) return { imports: '', hooks: '' };
+
+  // Dedupe hook imports by target — two belongsTo to the same model
+  // share the same query hook.
+  const hookImportNames = new Set<string>();
+  for (const rel of rels) {
+    hookImportNames.add(`use${pluralizeShared(rel.target)}Query`);
+  }
+
+  const helperImport = context.view.type.toLowerCase() === 'form'
+    ? 'getEntityDisplayName'
+    : 'resolveEntityDisplayName';
+
+  const importLines: string[] = [];
+  importLines.push(
+    `import { ${[...hookImportNames].join(', ')} } from '../hooks/useApi';`
+  );
+  importLines.push(`import { ${helperImport} } from '../lib/entity-display';`);
+
+  const hookLines = rels.map(rel =>
+    `  const { data: ${rel.name}Options = [] } = use${pluralizeShared(rel.target)}Query();`
+  );
+
+  return {
+    imports: importLines.join('\n'),
+    hooks: hookLines.join('\n'),
   };
 }
 

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

@@ -560,8 +560,56 @@ import { fileURLToPath } from 'url';`,
         }
 
         copyDir(templateDir, destDir);
+
+        // If the copied template didn't ship a specs/main.specly, load
+        // the canonical default spec from @specverse/engines/assets —
+        // same file app-demo's Server Manager "new spec" action uses,
+        // so both entry points start a user on the same footing. The
+        // template can opt out of this by shipping its own spec.
+        const specDestPath = join(destDir, 'specs', 'main.specly');
+        if (!existsSync(specDestPath)) {
+          try {
+            const { createRequire } = await import('module');
+            const require = createRequire(import.meta.url);
+            const enginesPkg = require.resolve('@specverse/engines/package.json');
+            const canonicalSpec = join(
+              dirname(enginesPkg),
+              'assets', 'templates', 'default', 'specs', 'main.specly'
+            );
+            if (existsSync(canonicalSpec)) {
+              let content = readFileSync(canonicalSpec, 'utf8');
+              for (const [key, val] of Object.entries(vars)) {
+                content = content.split(key).join(val);
+              }
+              mkdirSync(join(destDir, 'specs'), { recursive: true });
+              writeFileSync(specDestPath, content);
+            }
+          } catch { /* engines not installed or template missing — proceed */ }
+        }
+
+        // --static: flip any ReactAppRuntime mappings in the copied
+        // manifests to ReactAppStarter so the user gets standalone-starter
+        // output on first \`spv realize\` without having to re-pass the
+        // flag. Same semantic as \`spv realize --static\` — just applied
+        // at init time. Idempotent; no-op for templates without a frontend.
+        if (options.static) {
+          const manifestsDir = join(destDir, 'manifests');
+          if (existsSync(manifestsDir)) {
+            for (const f of readdirSync(manifestsDir)) {
+              if (!f.endsWith('.yaml') && !f.endsWith('.yml')) continue;
+              const p = join(manifestsDir, f);
+              const before = readFileSync(p, 'utf8');
+              const after = before.replace(
+                /instanceFactory:\\s*["']?ReactAppRuntime["']?/g,
+                'instanceFactory: "ReactAppStarter"'
+              );
+              if (after !== before) writeFileSync(p, after, 'utf8');
+            }
+          }
+        }
+
         console.log('Project created: ' + destDir);
-        console.log('Template: ' + templateName);
+        console.log('Template: ' + templateName + (options.static ? ' (static / ReactAppStarter)' : ''));
         console.log('');
 
         // Build the "Next steps" hint from the actual scripts the

package/libs/instance-factories/controllers/fastify.yaml

@@ -37,6 +37,12 @@ dependencies:
       version: "^11.1.0"
     - name: "@fastify/rate-limit"
       version: "^9.0.0"
+    # .env loading — main.ts calls `import 'dotenv/config'` first so
+    # PORT and other env vars populate before any module reads them.
+    # Mirrors vite's loadEnv on the frontend side, so `npm run
+    # dev:backend` honours the project's .env without a set -a dance.
+    - name: "dotenv"
+      version: "^16.4.0"
 
   dev:
     - name: "@types/node"
@@ -99,6 +105,7 @@ requirements:
         "fastify": "^5.8.3"
         "@fastify/cors": "^10.0.0"
         "yaml": "^2.3.0"
+        "dotenv": "^16.4.0"
       devDependencies:
         "tsx": "^4.0.0"
       scripts:

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

@@ -49,6 +49,27 @@ export default function generateFastifyServer(context: TemplateContext): string
  * Generated from SpecVerse specification
  */
 
+// Load .env from the closest ancestor that has one. Walks up from
+// this file's directory so the backend picks up the project-root
+// .env whether it's running in the monorepo layout
+// (generated/code/backend/src/main.ts with .env at generated/code/)
+// or the standalone layout (generated/code/src/main.ts with .env at
+// generated/code/). dotenv's default cwd-based behaviour doesn't
+// handle the monorepo case because npm workspaces \`cd\`s into the
+// workspace before running the script.
+import { config as loadEnv } from 'dotenv';
+import { existsSync } from 'fs';
+import { resolve as resolvePath, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+{
+  let dir = dirname(fileURLToPath(import.meta.url));
+  while (dir !== '/' && dir !== dirname(dir)) {
+    const candidate = join(dir, '.env');
+    if (existsSync(candidate)) { loadEnv({ path: candidate }); break; }
+    dir = dirname(dir);
+  }
+}
+
 import Fastify from 'fastify';
 import cors from '@fastify/cors';
 import { PrismaClient } from '@prisma/client';
@@ -112,9 +133,9 @@ ${hasEvents ? `    // Register WebSocket bridge for real-time frontend events
     // 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(', ')}\`);
+    console.log(\`API endpoints: ${modelNames.map((n: string) => `/api/${pluralizeLower(n)}`).join(', ')}\`);
 ${hasEvents ? `    console.log(\`WebSocket: ws://localhost:\${port}/ws\`);
-    console.log(\`Events: ${specEvents.join(', ')}\`);` : ''}
+    console.log(\`Events: ${specEvents.length} wired (GET /api/runtime/events for the full list)\`);` : ''}
   } catch (err) {
     fastify.log.error(err);
     process.exit(1);
@@ -124,3 +145,16 @@ ${hasEvents ? `    console.log(\`WebSocket: ws://localhost:\${port}/ws\`);
 start();
 `;
 }
+
+/**
+ * Minimal English pluralizer — matches the same rules the routes
+ * generator uses so the startup banner's route list agrees with the
+ * actual routes the server exposes. "Category" → "categories", not
+ * "categorys"; "Box" → "boxes"; "Item" → "items".
+ */
+function pluralizeLower(s: string): string {
+  const lower = s.toLowerCase();
+  if (/[^aeiou]y$/.test(lower)) return lower.slice(0, -1) + 'ies';
+  if (/(s|x|z|ch|sh)$/.test(lower)) return lower + 'es';
+  return lower + 's';
+}

package/libs/instance-factories/orms/templates/prisma/schema-generator.ts

@@ -168,9 +168,11 @@ function buildMissingBackRefs(
           r.target === target && (r.type === 'hasMany' || r.type === 'hasOne')
         );
         const needsFieldInFk = parentRelsToSameTarget.length > 1;
+        // Back-ref FK column — same camelCase convention as the forward
+        // belongsTo path above (see line ~455).
         const fkSuffix = needsFieldInFk
-          ? camelToSnake(fieldName) + '_id'
-          : camelToSnake(model.name.charAt(0).toLowerCase() + model.name.slice(1)) + '_id';
+          ? fieldName + 'Id'
+          : model.name.charAt(0).toLowerCase() + model.name.slice(1) + 'Id';
         const fkName = fkSuffix;
         const fkPadding = ' '.repeat(Math.max(1, 15 - fkName.length));
         const refFieldName = needsFieldInFk
@@ -451,8 +453,13 @@ function generateRelationship(rel: any, model: any, relationMap: Map<string, str
 
   switch (rel.type) {
     case 'belongsTo':
-      // Foreign key field — use snake_case for the FK column name
-      const fkBase = rel.foreignKey || camelToSnake(name) + '_id';
+      // Foreign key field — use camelCase, matching the casing of
+      // every other attribute the generator emits. Earlier revisions
+      // used snake_case here, which inconsistently mixed
+      // `createdAt` (camel) with `category_id` (snake) in the same
+      // schema and leaked through to API responses, breaking
+      // camelCase FK lookups on the frontend.
+      const fkBase = rel.foreignKey || name + 'Id';
       const fkPadding = ' '.repeat(Math.max(1, 15 - fkBase.length));
       // Add @unique if the parent has a hasOne relation pointing to this model
       const isUniqueFK = hasOneTargets.has(`${rel.target}->${model.name}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specverse/engines",
-  "version": "4.2.0",
+  "version": "4.2.2",
   "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry",
   "type": "module",
   "main": "dist/index.js",
@@ -44,6 +44,7 @@
   "dependencies": {
     "@specverse/types": "^4.1.0",
     "@specverse/entities": "^4.1.0",
+    "@specverse/runtime": "^4.1.22",
     "ajv": "^8.17.0",
     "ajv-formats": "^2.1.0",
     "glob": "^10.0.0",