@specverse/engines 4.1.30 → 4.2.1

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

@@ -0,0 +1,209 @@
+/**
+ * ReactAppStarter view emitter
+ *
+ * Given a view spec + model spec + expanded spec, emits a complete
+ * idiomatic React component source file as a string.
+ *
+ * Strategy 3 ("skeleton + rendered interior"): a hand-written
+ * skeleton template provides the idiomatic React outer structure
+ * (imports, hooks, props, layout). The canonical Tailwind adapter
+ * renders the pattern's interior as HTML. The html-to-jsx transformer
+ * converts the HTML to JSX. The emitter composes these.
+ *
+ * See README.md in this directory for the architecture.
+ */
+
+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
+ * inferred spec format — `view.type` drives skeleton selection,
+ * `view.model` identifies the primary model, `view.uiComponents` (if
+ * present) overrides inference defaults.
+ */
+export interface ViewSpec {
+  type: string;
+  model?: string;
+  uiComponents?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * The minimal shape of a model spec this emitter needs. Field details
+ * flow through to the Tailwind adapter which decides column selection.
+ */
+export interface ModelSpec {
+  name: string;
+  attributes: Record<string, unknown>;
+  relationships?: Record<string, unknown>;
+  lifecycles?: Record<string, unknown>;
+}
+
+export interface EmitContext {
+  view: ViewSpec;
+  viewName: string;          // e.g. "PostListView"
+  model: ModelSpec;
+  modelSchemas: Record<string, ModelSpec>;
+  /** Pluggable so we can stub the renderer in unit tests. */
+  renderBody: RenderBodyFn;
+}
+
+/**
+ * Render the body of a view as JSX-safe source — the exact string
+ * that is dropped at `{{BODY}}` in the skeleton.
+ *
+ * The renderBody implementation is responsible for the whole body
+ * pipeline: invoke the canonical Tailwind adapter for static shell
+ * rendering, run that HTML through `htmlToJsx`, and inject any JSX
+ * expressions (`.map()`, event handlers). Keeping it here means
+ * view-emitter stays a pure orchestrator and can't accidentally
+ * double-transform JSX that's already JSX.
+ */
+export type RenderBodyFn = (context: EmitContext) => string;
+
+/**
+ * Emit a complete .tsx file for a single view. Pure function — all
+ * inputs come in via the context argument so it's easy to test.
+ */
+export function emitView(context: EmitContext): string {
+  const skeleton = loadSkeleton(context.view.type);
+  const bodyJsx = context.renderBody(context);
+
+  const substitutions = buildSubstitutions(context, bodyJsx);
+  return applySubstitutions(skeleton, substitutions);
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Skeleton loading
+// ──────────────────────────────────────────────────────────────────────
+
+const SKELETON_BY_VIEW_TYPE: Record<string, string> = {
+  list: 'list.tsx.template',
+  detail: 'detail.tsx.template',
+  form: 'form.tsx.template',
+  dashboard: 'dashboard.tsx.template',
+  // Specialist types (board, timeline, calendar, analytics, workflow,
+  // wizard, comparison, settings, map, feed, profile) come online in
+  // Phase 2e.
+};
+
+function loadSkeleton(viewType: string): string {
+  const filename = SKELETON_BY_VIEW_TYPE[viewType.toLowerCase()];
+  if (!filename) {
+    throw new Error(
+      `No skeleton registered for view type "${viewType}". ` +
+      `Known types: ${Object.keys(SKELETON_BY_VIEW_TYPE).join(', ')}.`
+    );
+  }
+
+  const here = dirname(fileURLToPath(import.meta.url));
+  const path = join(here, 'skeletons', filename);
+  return readFileSync(path, 'utf8');
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Substitution
+// ──────────────────────────────────────────────────────────────────────
+
+interface Substitutions {
+  MODEL_NAME: string;
+  PLURAL_MODEL: string;
+  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'),
+  };
+}
+
+function applySubstitutions(template: string, subs: Substitutions): string {
+  let out = template;
+  for (const [key, value] of Object.entries(subs)) {
+    // Replace every occurrence of {{KEY}} — plain string substitution,
+    // no expression evaluation. Escape regex special chars in the key
+    // (defensive; keys are ASCII constants).
+    const pattern = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+    out = out.replace(pattern, value);
+  }
+  return out;
+}
+
+/**
+ * Minimal English pluralizer matching the adapter's conventions.
+ * Good enough for generated code — users can edit the output if they
+ * want a different pluralization.
+ */
+function pluralize(s: string): string {
+  if (/[^aeiou]y$/i.test(s)) return s.slice(0, -1) + 'ies';
+  if (/(s|x|z|ch|sh)$/i.test(s)) return s + 'es';
+  return s + 's';
+}

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;
@@ -557,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,7 +1,7 @@
 {
   "name": "@specverse/engines",
-  "version": "4.1.30",
-  "description": "SpecVerse toolchain \u2014 parser, inference, realize, generators, AI, registry",
+  "version": "4.2.1",
+  "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"
-}
+}