@specverse/engines 4.1.30 → 4.2.0

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

@@ -0,0 +1,72 @@
+/**
+ * {{MODEL_NAME}}ListView — generated by @specverse/realize (ReactAppStarter)
+ *
+ * Safe to edit. Edits are preserved across regeneration via content
+ * hashing (see .specverse-gen/hashes.json). To accept an upstream
+ * regeneration of this file, delete it first, then run `spv realize`.
+ */
+import { useState, useMemo } from 'react';
+import { use{{PLURAL_MODEL}}Query, useDelete{{MODEL_NAME}}Mutation } from '../hooks/useApi';
+import type { {{MODEL_NAME}} } from '../types/api';
+
+interface {{MODEL_NAME}}ListViewProps {
+  onSelect?: (item: {{MODEL_NAME}}) => void;
+  onCreate?: () => void;
+}
+
+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();
+  const [searchTerm, setSearchTerm] = useState('');
+
+  const filtered = useMemo(
+    () =>
+      items.filter((item: {{MODEL_NAME}}) =>
+        // Cast to `any` inside JSX context — `Record<string, unknown>`
+        // looks like a JSX opening tag to the TSX parser when this
+        // expression ends up inside JSX. `any` is safe here: we only
+        // read values for substring-matching against the search term.
+        Object.values(item as any).some(v =>
+          String(v ?? '').toLowerCase().includes(searchTerm.toLowerCase())
+        )
+      ),
+    [items, searchTerm]
+  );
+
+  if (isLoading) return <div className="p-4 text-gray-500">Loading {{PLURAL_LOWER}}…</div>;
+  if (error) return <div className="p-4 text-red-600">Error loading {{PLURAL_LOWER}}: {String(error)}</div>;
+
+  return (
+    <div className="p-6 space-y-4">
+      <div className="flex items-center justify-between">
+        <input
+          type="search"
+          placeholder="Search {{PLURAL_LOWER}}…"
+          value={searchTerm}
+          onChange={e => setSearchTerm(e.target.value)}
+          className="w-64 rounded border border-gray-300 px-3 py-2 text-sm"
+        />
+        <button
+          type="button"
+          onClick={onCreate}
+          className="rounded bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700"
+        >
+          + New {{MODEL_NAME}}
+        </button>
+      </div>
+
+      {/* Pattern-rendered list body (table + rows). Edit freely. */}
+      {{BODY}}
+
+      {filtered.length === 0 && (
+        <div className="p-8 text-center text-gray-400">No {{PLURAL_LOWER}} yet.</div>
+      )}
+
+      {deleteItem.isError && (
+        <div className="p-2 text-sm text-red-600">
+          Delete failed: {String(deleteItem.error)}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,151 @@
+/**
+ * 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';
+
+/**
+ * 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;
+}
+
+function buildSubstitutions(context: EmitContext, body: string): Substitutions {
+  const modelName = context.model.name;
+  const pluralModel = pluralize(modelName);
+  return {
+    MODEL_NAME: modelName,
+    PLURAL_MODEL: pluralModel,
+    PLURAL_LOWER: pluralModel.toLowerCase(),
+    SINGULAR_LOWER: modelName.toLowerCase(),
+    BODY: body,
+  };
+}
+
+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;

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.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"
-}
+}