@specverse/engines 4.2.2 → 4.3.1

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

@@ -30,6 +30,29 @@ export interface UseApiHooksStarterContext {
   manifest?: unknown;
 }
 
+/**
+ * Extract lifecycle metadata from a model for the Evolve mutation.
+ * Returns an array of { name, states } entries. Both normalized
+ * (`states: [{name}]`) and raw (`flow: "a -> b -> c"`) shapes handled.
+ */
+function extractLifecycles(model: any): Array<{ name: string; states: string[] }> {
+  const out: Array<{ name: string; states: string[] }> = [];
+  const lifecycles = (model?.lifecycles ?? {}) as Record<string, any>;
+  for (const [name, def] of Object.entries(lifecycles)) {
+    if (!def || typeof def !== 'object') continue;
+    let states: string[] = [];
+    if (Array.isArray(def.states)) {
+      states = def.states
+        .map((s: any) => typeof s === 'string' ? s : s?.name ?? s?.id ?? '')
+        .filter(Boolean);
+    } else if (typeof def.flow === 'string') {
+      states = def.flow.split(/\s*(?:->|,)\s*/).map((s: string) => s.trim()).filter(Boolean);
+    }
+    if (states.length > 0) out.push({ name, states });
+  }
+  return out;
+}
+
 export async function generate(context: UseApiHooksStarterContext): Promise<string> {
   const models = Object.keys(context.spec.models ?? {});
 
@@ -48,10 +71,13 @@ ${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,
-  });
+  // Only declare Content-Type: application/json when there's actually a
+  // body. Fastify's default JSON parser rejects empty-body requests that
+  // claim JSON (FST_ERR_CTP_EMPTY_JSON_BODY) — so DELETE / GET without
+  // bodies must NOT send the header.
+  const headers: Record<string, string> = {};
+  if (init?.body != null) headers['Content-Type'] = 'application/json';
+  const res = await fetch(url, { ...init, headers: { ...headers, ...init?.headers } });
   if (!res.ok) {
     throw new Error(\`\${res.status} \${res.statusText} — \${url}\`);
   }
@@ -60,18 +86,53 @@ async function fetchJSON<T = unknown>(url: string, init?: RequestInit): Promise<
 }
 `;
 
-  const hookBlocks = models.map(m => generateModelHooks(m)).join('\n\n');
+  const hookBlocks = models
+    .map(m => generateModelHooks(m, context.spec.models?.[m]))
+    .join('\n\n');
 
   return importsAndTypes + '\n' + hookBlocks + '\n';
 }
 
-function generateModelHooks(model: string): string {
+function generateModelHooks(model: string, modelDef: any): string {
   const plural = pluralize(model);
   const resource = plural.toLowerCase();
-  const modelLower = model.toLowerCase();
+  const lifecycles = extractLifecycles(modelDef);
+  const hasLifecycle = lifecycles.length > 0;
+
+  // Lifecycle metadata for the Evolve tab. Stored as a const so form
+  // skeletons can read state lists + primary lifecycle name without
+  // re-parsing the spec. One entry per declared lifecycle attribute.
+  const lifecycleBlock = hasLifecycle
+    ? `
+export const ${model.toUpperCase()}_LIFECYCLES = ${JSON.stringify(
+        Object.fromEntries(lifecycles.map(l => [l.name, { states: l.states }])),
+        null,
+        2,
+      )} as const;
+`
+    : '';
+
+  // Evolve mutation — only emitted for models with at least one
+  // lifecycle. Body shape matches the generated backend's evolve
+  // handler: { toState, lifecycleName? } → update that column.
+  const evolveHook = hasLifecycle
+    ? `
+export function useEvolve${model}Mutation() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: ({ id, toState, lifecycleName }: { id: string | number; toState: string; lifecycleName?: string }) =>
+      fetchJSON<${model}>(\`\${API_BASE}/api/${resource}/\${id}/evolve\`, {
+        method: 'PATCH',
+        body: JSON.stringify({ toState, lifecycleName }),
+      }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['${resource}'] }),
+  });
+}
+`
+    : '';
 
   return `// ─── ${model} ───────────────────────────────────────────────────
-
+${lifecycleBlock}
 export function use${plural}Query() {
   return useQuery({
     queryKey: ['${resource}'],
@@ -104,7 +165,7 @@ export function useUpdate${model}Mutation() {
   return useMutation({
     mutationFn: ({ id, data }: { id: string | number; data: Partial<${model}> }) =>
       fetchJSON<${model}>(\`\${API_BASE}/api/${resource}/\${id}\`, {
-        method: 'PATCH',
+        method: 'PUT',
         body: JSON.stringify(data),
       }),
     onSuccess: () => qc.invalidateQueries({ queryKey: ['${resource}'] }),
@@ -118,7 +179,7 @@ export function useDelete${model}Mutation() {
       fetchJSON<void>(\`\${API_BASE}/api/${resource}/\${id}\`, { method: 'DELETE' }),
     onSuccess: () => qc.invalidateQueries({ queryKey: ['${resource}'] }),
   });
-}`;
+}${evolveHook}`;
 }
 
 export default generate;

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

@@ -16,7 +16,9 @@
 import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { extractBelongsToTargets, pluralize as pluralizeShared } from './belongs-to.js';
+import { walkPatternSection } from '@specverse/runtime/views/core';
+import { extractBelongsToTargets, extractHasManyTargets, pluralize as pluralizeShared } from './belongs-to.js';
+import { emitJsxSource } from './emit-jsx-source.js';
 
 /**
  * The minimal shape of a view spec this emitter needs. Matches the
@@ -115,23 +117,57 @@ interface Substitutions {
   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.
+   * Extra import lines that pull in the hooks and display-name
+   * helpers this view needs for related models (belongsTo dropdowns,
+   * belongsTo FK resolution, hasMany lists in detail views). Empty
+   * string when there are no related models to wire.
    */
   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.
+   * Extra hook calls inside the component body — one per related
+   * target. belongsTo → \`${relName}Options\`, hasMany → \`${relName}All\`.
+   * Empty string when none.
    */
   RELATED_HOOKS: string;
+  /**
+   * Detail-view tabbed-related-lists state. A \`useState\` line
+   * declaring \`relatedTab\` + \`setRelatedTab\` when the detail has
+   * more than one hasMany. Empty otherwise.
+   */
+  RELATED_TAB_STATE: string;
+  /**
+   * Detail-view tabbed-related-lists import line. \`import { useState }
+   * from 'react';\` when tabs are emitted, empty otherwise (strict TS
+   * rejects unused imports).
+   */
+  RELATED_TAB_IMPORT: string;
+  /**
+   * Form-view lifecycle substitutions. Populated only when the model
+   * has >=1 lifecycle. Drive the Edit/Evolve tab block in form.tsx.template.
+   */
+  LIFECYCLE_IMPORTS: string;
+  LIFECYCLE_HOOK: string;
+  LIFECYCLE_STATE: string;
+  LIFECYCLE_HANDLER: string;
+  LIFECYCLE_PANEL: string;
+  HAS_LIFECYCLES: string;
+  /**
+   * Form-view body split into two slots so the Create/Update button
+   * row can sit BETWEEN the fields and the existing-entities list
+   * (matching app-demo's layout). FIELDS_BODY goes inside <form>,
+   * EXISTING_LIST_BODY after the button row, outside <form>. Empty
+   * for non-form views.
+   */
+  FIELDS_BODY: string;
+  EXISTING_LIST_BODY: string;
 }
 
 function buildSubstitutions(context: EmitContext, body: string): Substitutions {
   const modelName = context.model.name;
   const pluralModel = pluralize(modelName);
   const { imports, hooks } = buildBelongsToWiring(context);
+  const lifecycle = buildLifecycleSubstitutions(context);
+  const { fieldsBody, existingListBody } = buildFormSplitBodies(context);
   return {
     MODEL_NAME: modelName,
     PLURAL_MODEL: pluralModel,
@@ -140,9 +176,204 @@ function buildSubstitutions(context: EmitContext, body: string): Substitutions {
     BODY: body,
     RELATED_IMPORTS: imports,
     RELATED_HOOKS: hooks,
+    RELATED_TAB_STATE: buildRelatedTabState(context),
+    RELATED_TAB_IMPORT: buildRelatedTabImport(context),
+    FIELDS_BODY: fieldsBody,
+    EXISTING_LIST_BODY: existingListBody,
+    ...lifecycle,
+  };
+}
+
+/**
+ * Walk the form pattern's `fields` and `existing-entities-list`
+ * sections separately so the skeleton can place them in different
+ * DOM locations (fields inside <form>, existing-list outside +
+ * below the button row). Empty for non-form views.
+ */
+function buildFormSplitBodies(context: EmitContext): { fieldsBody: string; existingListBody: string } {
+  if (context.view.type.toLowerCase() !== 'form') {
+    return { fieldsBody: '', existingListBody: '' };
+  }
+  const walkCtx = {
+    model: context.model,
+    modelSchemas: context.modelSchemas as any,
+    view: context.view as any,
+  };
+  const imports = new Set<string>();
+  const fieldsNodes = walkPatternSection('form-view', 'fields', walkCtx);
+  const listNodes = walkPatternSection('form-view', 'existing-entities-list', walkCtx);
+  return {
+    fieldsBody: emitJsxSource(fieldsNodes, { imports, indent: 10 }),
+    existingListBody: emitJsxSource(listNodes, { imports, indent: 6 }),
+  };
+}
+
+/**
+ * Compute the form-view lifecycle block. Empty across the board for
+ * non-form views or models without declared lifecycles — strict TS
+ * rejects unused imports, so all placeholders must be conditional.
+ *
+ * The generated Evolve tab: a state picker + Save button that invokes
+ * \`useEvolve{Model}Mutation\` with { id, toState, lifecycleName }.
+ * Uses the primary (first-declared) lifecycle to drive the picker —
+ * multi-lifecycle support (a picker-per-lifecycle) is a later extension.
+ */
+function buildLifecycleSubstitutions(context: EmitContext): {
+  LIFECYCLE_IMPORTS: string;
+  LIFECYCLE_HOOK: string;
+  LIFECYCLE_STATE: string;
+  LIFECYCLE_HANDLER: string;
+  LIFECYCLE_PANEL: string;
+  HAS_LIFECYCLES: string;
+} {
+  const isForm = context.view.type.toLowerCase() === 'form';
+  const lifecycles = extractLifecycles(context.model);
+  if (!isForm || lifecycles.length === 0) {
+    return {
+      LIFECYCLE_IMPORTS: '',
+      LIFECYCLE_HOOK: '',
+      LIFECYCLE_STATE: '',
+      LIFECYCLE_HANDLER: '',
+      LIFECYCLE_PANEL: '',
+      HAS_LIFECYCLES: 'false',
+    };
+  }
+
+  const modelName = context.model.name;
+  const primary = lifecycles[0];
+  const lifecyclesConst = `${modelName.toUpperCase()}_LIFECYCLES`;
+
+  return {
+    LIFECYCLE_IMPORTS: `  useEvolve${modelName}Mutation,\n  ${lifecyclesConst},`,
+    LIFECYCLE_HOOK: `  const evolveItem = useEvolve${modelName}Mutation();`,
+    LIFECYCLE_STATE: `  const [targetState, setTargetState] = useState<string>('');`,
+    LIFECYCLE_HANDLER: `  const handleEvolveSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    if (!targetState) return;
+    try {
+      const result = await evolveItem.mutateAsync({
+        id: entityId as any,
+        toState: targetState,
+        lifecycleName: '${primary.name}',
+      });
+      onSuccess?.(result as ${modelName});
+    } catch {
+      // Evolve errors are surfaced via evolveItem.isError.
+    }
+  };`,
+    LIFECYCLE_PANEL: buildLifecyclePanel(modelName, primary, lifecyclesConst),
+    HAS_LIFECYCLES: 'true',
   };
 }
 
+function buildLifecyclePanel(
+  modelName: string,
+  primary: { name: string; states: string[] },
+  lifecyclesConst: string,
+): string {
+  return `      {showTabs && activeTab === 'evolve' && (
+        <form onSubmit={handleEvolveSubmit} className="space-y-6">
+          <div className="rounded-lg border border-gray-200 bg-white p-6 dark:border-gray-700 dark:bg-gray-900">
+            <dl className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+              <div>
+                <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">Current ${humanize(primary.name)}</dt>
+                <dd className="mt-1">
+                  <span className="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-purple-100 text-purple-800 dark:bg-purple-900 dark:text-purple-200">
+                    {String((existing as any)?.${primary.name} ?? '')}
+                  </span>
+                </dd>
+              </div>
+              <div>
+                <label htmlFor="evolve-target" className="block text-sm font-medium text-gray-500 dark:text-gray-400">Next ${humanize(primary.name)}</label>
+                <select
+                  id="evolve-target"
+                  value={targetState}
+                  onChange={e => setTargetState(e.target.value)}
+                  className="mt-1 w-full rounded border border-gray-300 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100"
+                >
+                  <option value="">— choose —</option>
+                  {${lifecyclesConst}.${primary.name}.states.map(s => (
+                    <option key={s} value={s}>{s}</option>
+                  ))}
+                </select>
+              </div>
+            </dl>
+          </div>
+
+          <div>
+            <button
+              type="submit"
+              disabled={evolveItem.isPending || !targetState}
+              className="rounded bg-purple-600 px-4 py-2 text-sm font-medium text-white hover:bg-purple-700 disabled:opacity-60"
+            >
+              {evolveItem.isPending ? 'Evolving…' : \`Evolve to \${targetState || '…'}\`}
+            </button>
+          </div>
+
+          {evolveItem.isError && (
+            <div className="rounded border border-red-200 bg-red-50 p-3 text-sm text-red-700 dark:border-red-800 dark:bg-red-950 dark:text-red-300">
+              Evolve failed: {String(evolveItem.error)}
+            </div>
+          )}
+        </form>
+      )}`;
+}
+
+/**
+ * Local copy of extractLifecycles to avoid importing from the hook
+ * generator. Matches the runtime helper in lifecycle-helpers.ts.
+ */
+function extractLifecycles(model: any): Array<{ name: string; states: string[] }> {
+  const out: Array<{ name: string; states: string[] }> = [];
+  const lifecycles = (model?.lifecycles ?? {}) as Record<string, any>;
+  for (const [name, def] of Object.entries(lifecycles)) {
+    if (!def || typeof def !== 'object') continue;
+    let states: string[] = [];
+    if (Array.isArray(def.states)) {
+      states = def.states
+        .map((s: any) => (typeof s === 'string' ? s : s?.name ?? s?.id ?? ''))
+        .filter(Boolean);
+    } else if (typeof def.flow === 'string') {
+      states = def.flow.split(/\s*(?:->|,)\s*/).map((s: string) => s.trim()).filter(Boolean);
+    }
+    if (states.length > 0) out.push({ name, states });
+  }
+  return out;
+}
+
+function humanize(name: string): string {
+  return name
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, c => c.toUpperCase())
+    .trim();
+}
+
+/**
+ * Return the \`useState\` import line for detail views with tabs.
+ * Empty for everything else — strict TS rejects unused imports, so
+ * we emit the import only when the state is actually declared.
+ */
+function buildRelatedTabImport(context: EmitContext): string {
+  if (context.view.type.toLowerCase() !== 'detail') return '';
+  const hasMany = extractHasManyTargets(context.model, context.modelSchemas);
+  if (hasMany.length < 2) return '';
+  return `import { useState } from 'react';`;
+}
+
+/**
+ * Emit a \`useState\` call only when the detail view will render
+ * tabs — i.e. when the model has 2+ hasMany relationships. The tab
+ * state defaults to the first relationship's name. For other view
+ * types or single-hasMany detail views, no state is needed.
+ */
+function buildRelatedTabState(context: EmitContext): string {
+  if (context.view.type.toLowerCase() !== 'detail') return '';
+  const hasMany = extractHasManyTargets(context.model, context.modelSchemas);
+  if (hasMany.length < 2) return '';
+  const firstName = hasMany[0].name;
+  return `  const [relatedTab, setRelatedTab] = useState<string>('${firstName}');`;
+}
+
 /**
  * Compute the belongsTo wiring for a view: one import line per unique
  * target hook, one hook call per relationship (even if two relations
@@ -155,29 +386,132 @@ function buildSubstitutions(context: EmitContext, body: string): Substitutions {
  *     (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: '' };
+  const belongsTo = extractBelongsToTargets(context.model);
+  // hasMany wiring is only needed by the detail view (for its
+  // related-lists section). Other view types skip it to avoid
+  // unused-import TS errors.
+  const isDetail = context.view.type.toLowerCase() === 'detail';
+  const hasMany = isDetail
+    ? extractHasManyTargets(context.model, context.modelSchemas)
+    : [];
+
+  // For detail's related tables to resolve FK columns (e.g. Task.project
+  // in a User → Tasks table), we also need query hooks for each
+  // hasMany-target's own belongsTo targets. Skip the back-reference
+  // target (pointing at us) since that column is filtered out.
+  const crossBelongsTo: BelongsToLike[] = [];
+  if (isDetail) {
+    for (const rel of hasMany) {
+      const targetModel = context.modelSchemas[rel.target];
+      if (!targetModel) continue;
+      const targetFK = rel.foreignKey;
+      for (const btm of extractBelongsToTargets(targetModel)) {
+        if (`${btm.name}Id` === targetFK) continue;  // skip back-ref
+        crossBelongsTo.push(btm);
+      }
+    }
+  }
+
+  if (belongsTo.length === 0 && hasMany.length === 0 && crossBelongsTo.length === 0) {
+    // Detail view still needs getEntityDisplayName for its picker +
+    // formatDisplayValue for field rows, even when the model has no
+    // relationships.
+    const vt = context.view.type.toLowerCase();
+    if (vt === 'detail') {
+      return {
+        imports: `import { getEntityDisplayName, formatDisplayValue } from '../lib/entity-display';`,
+        hooks: '',
+      };
+    }
+    // List / dashboard without relationships still need formatDisplayValue
+    // for non-FK cells.
+    if (vt === 'list' || vt === 'dashboard') {
+      return {
+        imports: `import { formatDisplayValue } from '../lib/entity-display';`,
+        hooks: '',
+      };
+    }
+    return { imports: '', hooks: '' };
+  }
 
-  // Dedupe hook imports by target — two belongsTo to the same model
+  // Dedupe hook imports by target — relationships to the same model
   // share the same query hook.
   const hookImportNames = new Set<string>();
-  for (const rel of rels) {
+  for (const rel of belongsTo) {
+    hookImportNames.add(`use${pluralizeShared(rel.target)}Query`);
+  }
+  for (const rel of hasMany) {
+    hookImportNames.add(`use${pluralizeShared(rel.target)}Query`);
+  }
+  for (const rel of crossBelongsTo) {
     hookImportNames.add(`use${pluralizeShared(rel.target)}Query`);
   }
 
-  const helperImport = context.view.type.toLowerCase() === 'form'
-    ? 'getEntityDisplayName'
-    : 'resolveEntityDisplayName';
+  // Helpers needed per view type (strict TS rejects unused imports,
+  // so we only list what the emitted code actually references):
+  //   - form uses getEntityDisplayName(opt) for dropdown labels
+  //   - list / dashboard use resolveEntityDisplayName(id, list) for
+  //     FK columns
+  //   - detail main section uses resolveEntityDisplayName when there
+  //     are belongsTo rows; the related-lists section uses
+  //     resolveEntityDisplayName for FK columns in the full-column
+  //     path, or getEntityDisplayName in the one-column fallback
+  //     path (used when a hasMany target's schema isn't in
+  //     context.modelSchemas).
+  const viewType = context.view.type.toLowerCase();
+  const helperImports = new Set<string>();
+  if (viewType === 'form') {
+    helperImports.add('getEntityDisplayName');
+  } else if (viewType === 'detail') {
+    // Detail view always uses getEntityDisplayName for the entity
+    // picker dropdown (per-skeleton, not per-section).
+    helperImports.add('getEntityDisplayName');
+    helperImports.add('formatDisplayValue');  // field-list + related-tables cells.
+    if (belongsTo.length > 0 || crossBelongsTo.length > 0) {
+      helperImports.add('resolveEntityDisplayName');
+    }
+  } else if (viewType === 'list' || viewType === 'dashboard') {
+    helperImports.add('resolveEntityDisplayName');
+    helperImports.add('formatDisplayValue');  // table-content + recent-items cells.
+  } else {
+    helperImports.add('resolveEntityDisplayName');
+  }
 
   const importLines: string[] = [];
   importLines.push(
     `import { ${[...hookImportNames].join(', ')} } from '../hooks/useApi';`
   );
-  importLines.push(`import { ${helperImport} } from '../lib/entity-display';`);
+  if (helperImports.size > 0) {
+    importLines.push(`import { ${[...helperImports].join(', ')} } from '../lib/entity-display';`);
+  }
 
-  const hookLines = rels.map(rel =>
-    `  const { data: ${rel.name}Options = [] } = use${pluralizeShared(rel.target)}Query();`
-  );
+  // belongsTo hooks → \`${relName}Options\` arrays used in dropdowns
+  // and FK resolvers. hasMany hooks → \`${relName}All\` arrays that
+  // the detail composer filters by the back-reference FK. Cross-
+  // belongsTo hooks → \`${relName}Options\` so related tables in the
+  // detail view can resolve their FK columns to display names.
+  const hookLines: string[] = [];
+  for (const rel of belongsTo) {
+    hookLines.push(
+      `  const { data: ${rel.name}Options = [] } = use${pluralizeShared(rel.target)}Query();`
+    );
+  }
+  for (const rel of hasMany) {
+    hookLines.push(
+      `  const { data: ${rel.name}All = [] } = use${pluralizeShared(rel.target)}Query();`
+    );
+  }
+  // Dedupe cross-belongsTo options by name: if two hasMany targets
+  // both have a \`project\` belongsTo, we only need one \`projectOptions\`.
+  const emittedOptionsVars = new Set(belongsTo.map(r => `${r.name}Options`));
+  for (const rel of crossBelongsTo) {
+    const varName = `${rel.name}Options`;
+    if (emittedOptionsVars.has(varName)) continue;
+    emittedOptionsVars.add(varName);
+    hookLines.push(
+      `  const { data: ${varName} = [] } = use${pluralizeShared(rel.target)}Query();`
+    );
+  }
 
   return {
     imports: importLines.join('\n'),
@@ -185,6 +519,13 @@ function buildBelongsToWiring(context: EmitContext): { imports: string; hooks: s
   };
 }
 
+/**
+ * Minimal "belongsTo-like" shape — both extractBelongsToTargets
+ * results and the cross-target equivalent use this. Declared here
+ * just to keep the wiring function's signatures tight.
+ */
+type BelongsToLike = { name: string; target: string };
+
 function applySubstitutions(template: string, subs: Substitutions): string {
   let out = template;
   for (const [key, value] of Object.entries(subs)) {

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

@@ -14,7 +14,9 @@ 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';
+import { emitEntityDisplay, emitUseResizableSidebar, emitUseAppEvents } from './helpers-emitter.js';
+import { emitFieldInput, emitOperationExecutor, emitOperationResultView } from './operation-emitters.js';
+import { collectOperationViews, emitOperationView } from './operation-view-generator.js';
 
 /**
  * The four primary view types Factory B currently emits. Specialist
@@ -46,6 +48,12 @@ export interface ExpandedSpec {
   models?: Record<string, ModelSpec>;
   /** Views keyed by view name (e.g. "PostListView"). */
   views?: Record<string, ViewSpec & { type: string; model?: string }>;
+  /** Controllers keyed by name (e.g. "PostController"). Non-standard
+   *  commands get auto-generated operation views. */
+  controllers?: Record<string, any>;
+  /** Services keyed by name (e.g. "AuthService"). Every operation
+   *  gets an auto-generated operation view. */
+  services?: Record<string, any> | any[];
 }
 
 export interface GeneratedFiles {
@@ -105,8 +113,27 @@ export async function generate(context: ViewsGeneratorContext): Promise<Generate
     );
   }
 
+  // Auto-generated operation views — one per non-standard controller
+  // command + service operation. Uses the same lib components as
+  // handwritten operation views would; emitted into src/views/ alongside
+  // declared views. App.tsx sidebar groups them as Dev (see below).
+  const operationViews = collectOperationViews(spec);
+  for (const desc of operationViews) {
+    files[`src/views/${desc.viewName}.tsx`] = emitOperationView(desc);
+  }
+
   // Local helpers
   files['src/lib/entity-display.ts'] = emitEntityDisplay();
+  files['src/hooks/useResizableSidebar.ts'] = emitUseResizableSidebar();
+  files['src/hooks/useAppEvents.tsx'] = emitUseAppEvents();
+  // Operation-view lib (only needed when at least one operation view
+  // is emitted — otherwise FieldInput / OperationExecutor / etc. go
+  // unused and trigger TS errors for unused imports from nowhere).
+  if (operationViews.length > 0) {
+    files['src/lib/FieldInput.tsx'] = emitFieldInput();
+    files['src/lib/OperationExecutor.tsx'] = emitOperationExecutor();
+    files['src/lib/OperationResultView.tsx'] = emitOperationResultView();
+  }
 
   return files;
 }

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

@@ -264,9 +264,21 @@ function generateHandlerBody(
   await handler.delete(id);
   return reply.status(204).send();
 } catch (error) {
+  // Prisma's P2003 is the foreign-key-constraint-violated error. When
+  // a ${lowerModel} has children (hasMany relationships not declared
+  // with 'cascade'), SQLite / Postgres refuse the delete and we land
+  // here. Return a 409 Conflict with a specific hint rather than a 500
+  // with a raw Prisma dump — the frontend shows the message verbatim.
+  const msg = error instanceof Error ? error.message : String(error);
+  if (msg.includes('P2003') || msg.toLowerCase().includes('foreign key constraint')) {
+    return reply.status(409).send({
+      error: 'Cannot delete ${lowerModel}',
+      message: \`This ${lowerModel} has related records. Delete those first, or declare the relationship with 'cascade' in your spec to delete them automatically.\`
+    });
+  }
   return reply.status(500).send({
     error: 'Failed to delete ${lowerModel}',
-    message: error instanceof Error ? error.message : String(error)
+    message: msg
   });
 }`;
 

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

@@ -136,6 +136,24 @@ ${hasEvents ? `    // Register WebSocket bridge for real-time frontend events
     console.log(\`API endpoints: ${modelNames.map((n: string) => `/api/${pluralizeLower(n)}`).join(', ')}\`);
 ${hasEvents ? `    console.log(\`WebSocket: ws://localhost:\${port}/ws\`);
     console.log(\`Events: ${specEvents.length} wired (GET /api/runtime/events for the full list)\`);` : ''}
+
+    // Graceful shutdown — without these handlers, Ctrl-C leaves open
+    // WebSocket connections + Prisma clients hanging, and tsx watch
+    // reports "Previous process hasn't exited yet. Force killing...".
+    // Drain Fastify (closes HTTP + WS), then disconnect Prisma, then exit.
+    const shutdown = async (signal: string) => {
+      try {
+        fastify.log.info(\`Received \${signal}, closing server...\`);
+        await fastify.close();
+        try { await (prisma as any).$disconnect?.(); } catch { /* ignore */ }
+        process.exit(0);
+      } catch (err) {
+        fastify.log.error({ err }, 'Error during shutdown');
+        process.exit(1);
+      }
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
   } catch (err) {
     fastify.log.error(err);
     process.exit(1);

package/package.json

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