@specverse/engines 4.1.30 → 4.2.0

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

@@ -0,0 +1,139 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as ts from 'typescript';
+import { generate, type ExpandedSpec } from '../views-generator.js';
+
+function makeSpec(): ExpandedSpec {
+  return {
+    models: {
+      Post: {
+        name: 'Post',
+        attributes: {
+          id: { type: 'UUID', required: true, auto: 'uuid4' },
+          title: { type: 'String', required: true },
+          body: { type: 'Text', required: false },
+        },
+      },
+      Author: {
+        name: 'Author',
+        attributes: {
+          id: { type: 'UUID', required: true, auto: 'uuid4' },
+          name: { type: 'String', required: true },
+        },
+      },
+    },
+    views: {},
+  };
+}
+
+function assertValidTsx(source: string, label: string): void {
+  const result = ts.transpileModule(source, {
+    compilerOptions: {
+      jsx: ts.JsxEmit.Preserve,
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      strict: false,
+    },
+    reportDiagnostics: true,
+  });
+  const errors = result.diagnostics?.filter(d => d.category === ts.DiagnosticCategory.Error) ?? [];
+  if (errors.length > 0) {
+    const message = errors
+      .map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n'))
+      .join('\n');
+    throw new Error(`${label} failed to parse as TSX:\n${message}\n\n--- source ---\n${source}`);
+  }
+}
+
+describe('views-generator.generate', () => {
+  it('emits 4 view files per model plus the helpers file', async () => {
+    const files = await generate({ spec: makeSpec() });
+    const paths = Object.keys(files);
+    expect(paths).toContain('src/views/PostListView.tsx');
+    expect(paths).toContain('src/views/PostDetailView.tsx');
+    expect(paths).toContain('src/views/PostFormView.tsx');
+    expect(paths).toContain('src/views/PostDashboardView.tsx');
+    expect(paths).toContain('src/views/AuthorListView.tsx');
+    expect(paths).toContain('src/views/AuthorDetailView.tsx');
+    expect(paths).toContain('src/views/AuthorFormView.tsx');
+    expect(paths).toContain('src/views/AuthorDashboardView.tsx');
+    expect(paths).toContain('src/lib/entity-display.ts');
+    // 2 models × 4 view types + 1 helper = 9 files.
+    expect(paths.length).toBe(9);
+  });
+
+  it('every emitted view file parses as valid TSX', async () => {
+    const files = await generate({ spec: makeSpec() });
+    for (const [path, source] of Object.entries(files)) {
+      if (path.endsWith('.tsx')) assertValidTsx(source, path);
+    }
+  });
+
+  it('uses a user-declared view spec in preference to a synthesized default', async () => {
+    const spec: ExpandedSpec = {
+      models: {
+        Post: {
+          name: 'Post',
+          attributes: {
+            id: { type: 'UUID', auto: 'uuid4' },
+            title: { type: 'String', required: true },
+          },
+        },
+      },
+      views: {
+        PostListView: {
+          type: 'list',
+          model: 'Post',
+          uiComponents: {
+            customTable: {
+              type: 'table',
+              properties: {
+                columns: ['SUPER CUSTOM COLUMN'],
+              },
+            },
+          },
+        },
+      },
+    };
+    const files = await generate({ spec });
+    const out = files['src/views/PostListView.tsx'];
+    // The user's custom column header is not directly visible because
+    // the current composer ignores user uiComponents (it infers
+    // columns from the model). But the view spec flows through — if
+    // we later teach the composer to honour uiComponents, this test
+    // anchors the contract.
+    expect(out).toBeDefined();
+    expect(out).toContain('export function PostListView');
+  });
+
+  it('warns on specialist view types and skips them', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const spec: ExpandedSpec = {
+        models: {
+          Post: { name: 'Post', attributes: { id: { auto: 'uuid4' }, title: {} } },
+        },
+        views: {
+          PostBoardView: { type: 'board', model: 'Post' },
+          PostTimelineView: { type: 'timeline', model: 'Post' },
+        },
+      };
+      const files = await generate({ spec });
+      expect(files['src/views/PostBoardView.tsx']).toBeUndefined();
+      expect(files['src/views/PostTimelineView.tsx']).toBeUndefined();
+      expect(warn).toHaveBeenCalled();
+      const warning = warn.mock.calls[0][0] as string;
+      expect(warning).toContain('Skipped');
+      expect(warning).toContain('board');
+      expect(warning).toContain('timeline');
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('handles an empty models map gracefully', async () => {
+    const files = await generate({ spec: { models: {}, views: {} } });
+    // Only the helpers file is emitted; no view files.
+    expect(Object.keys(files)).toEqual(['src/lib/entity-display.ts']);
+  });
+});

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

@@ -0,0 +1,141 @@
+/**
+ * App.tsx generator for ReactAppStarter
+ *
+ * Generates a simple App shell that routes between the emitted view
+ * components. Not using react-router — the starter output is
+ * deliberately low-magic. Users can add routing when they need
+ * URL-level view selection; for now, internal state drives it.
+ *
+ * Output:
+ *  - sidebar nav listing every (model × view-type)
+ *  - a main area rendering the selected view
+ *  - QueryClientProvider at the root
+ */
+
+import type { ExpandedSpec } from './views-generator.js';
+
+export interface AppGeneratorContext {
+  spec: ExpandedSpec;
+  manifest?: unknown;
+}
+
+export async function generate(context: AppGeneratorContext): Promise<string> {
+  const models = Object.keys(context.spec.models ?? {});
+  const imports = buildImports(models);
+  const navEntries = buildNavEntries(models);
+  const viewSwitch = buildViewSwitch(models);
+
+  return `/**
+ * App.tsx — generated by @specverse/realize (ReactAppStarter)
+ *
+ * Safe to edit. Edits are preserved across regeneration via content
+ * hashing. This is a minimal shell: a sidebar listing every
+ * (model, view-type) plus a main area that renders the selection.
+ * Swap in react-router or your preferred routing library when the
+ * app needs URL-driven navigation.
+ */
+import { useState } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+${imports}
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { staleTime: 5 * 60 * 1000, retry: 1 },
+  },
+});
+
+type Selection = {
+  model: string;
+  view: 'list' | 'detail' | 'form' | 'dashboard';
+  entityId?: string | number;
+};
+
+function Inner() {
+  const [selection, setSelection] = useState<Selection>(${models.length > 0 ? `{ model: '${models[0]}', view: 'list' }` : `{ model: '', view: 'list' }`});
+
+  const select = (model: string, view: Selection['view']) =>
+    setSelection({ model, view });
+
+  return (
+    <div className="min-h-screen flex bg-gray-50 dark:bg-gray-950">
+      <aside className="w-64 shrink-0 border-r border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900">
+        <div className="p-4 border-b border-gray-200 dark:border-gray-800">
+          <h1 className="text-lg font-semibold text-gray-900 dark:text-gray-100">App</h1>
+        </div>
+        <nav className="p-2 space-y-4">
+${navEntries}
+        </nav>
+      </aside>
+
+      <main className="flex-1 overflow-auto">
+${viewSwitch}
+      </main>
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Inner />
+    </QueryClientProvider>
+  );
+}
+`;
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────────────────────
+
+function buildImports(models: string[]): string {
+  return models.flatMap(m => [
+    `import { ${m}ListView } from './views/${m}ListView';`,
+    `import { ${m}DetailView } from './views/${m}DetailView';`,
+    `import { ${m}FormView } from './views/${m}FormView';`,
+    `import { ${m}DashboardView } from './views/${m}DashboardView';`,
+  ]).join('\n');
+}
+
+function buildNavEntries(models: string[]): string {
+  if (models.length === 0) {
+    return '          <p className="text-sm text-gray-400 px-2">No models in this spec.</p>';
+  }
+  return models.map(m => `          <div>
+            <div className="px-2 pb-1 text-xs font-semibold uppercase tracking-wider text-gray-500 dark:text-gray-400">
+              ${m}
+            </div>
+            <button type="button" onClick={() => select('${m}', 'list')} className="${navButtonCls('list')}">List</button>
+            <button type="button" onClick={() => select('${m}', 'dashboard')} className="${navButtonCls('dashboard')}">Dashboard</button>
+            <button type="button" onClick={() => select('${m}', 'form')} className="${navButtonCls('form')}">New</button>
+          </div>`).join('\n');
+}
+
+function navButtonCls(_view: string): string {
+  return (
+    'block w-full text-left rounded px-2 py-1 text-sm ' +
+    'text-gray-700 hover:bg-gray-100 ' +
+    'dark:text-gray-300 dark:hover:bg-gray-800'
+  );
+}
+
+function buildViewSwitch(models: string[]): string {
+  if (models.length === 0) {
+    return '        <p className="p-6 text-sm text-gray-400">No models — add one to your .specly file and run <code>spv realize</code>.</p>';
+  }
+  const branches = models.flatMap(m => [
+    `        {selection.model === '${m}' && selection.view === 'list' && (
+          <${m}ListView onSelect={item => setSelection({ model: '${m}', view: 'detail', entityId: (item as any).id })} onCreate={() => setSelection({ model: '${m}', view: 'form' })} />
+        )}`,
+    `        {selection.model === '${m}' && selection.view === 'detail' && selection.entityId !== undefined && (
+          <${m}DetailView entityId={selection.entityId} onEdit={item => setSelection({ model: '${m}', view: 'form', entityId: (item as any).id })} onBack={() => setSelection({ model: '${m}', view: 'list' })} onDeleted={() => setSelection({ model: '${m}', view: 'list' })} />
+        )}`,
+    `        {selection.model === '${m}' && selection.view === 'form' && (
+          <${m}FormView mode={selection.entityId ? 'update' : 'create'} entityId={selection.entityId} onSuccess={() => setSelection({ model: '${m}', view: 'list' })} onCancel={() => setSelection({ model: '${m}', view: 'list' })} />
+        )}`,
+    `        {selection.model === '${m}' && selection.view === 'dashboard' && (
+          <${m}DashboardView onSelect={item => setSelection({ model: '${m}', view: 'detail', entityId: (item as any).id })} />
+        )}`,
+  ]);
+  return branches.join('\n');
+}

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

@@ -0,0 +1,174 @@
+/**
+ * Dashboard-view body composer for ReactAppStarter
+ *
+ * Minimal starter-kit dashboard: metric cards derived from the list
+ * query (total count; enum-field breakdowns if the model has a status-
+ * like attribute), plus a compact preview of recent records.
+ *
+ * Aggregation / charts are deferred — they need backend endpoints
+ * (`/api/posts/metrics`, `/api/posts/by-month`, …) that the starter
+ * kit doesn't assume. TODO comments flag the extension points.
+ */
+
+import { METADATA_FIELDS } from '@specverse/runtime/views/core';
+import type { EmitContext, ModelSpec } from './view-emitter.js';
+
+const METADATA_FIELD_NAMES = new Set(METADATA_FIELDS);
+
+export function composeDashboardBody(context: EmitContext): string {
+  const modelName = context.model.name;
+  const previewColumns = inferPreviewColumns(context.model);
+  const enumFields = inferEnumFields(context.model);
+
+  const lines: string[] = [];
+
+  // ── Metrics row ────────────────────────────────────────────────────
+  lines.push('<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">');
+  lines.push(...renderTotalCard(modelName));
+  for (const enumField of enumFields) {
+    lines.push(...renderEnumBreakdownCard(enumField));
+  }
+  if (enumFields.length === 0) {
+    lines.push(...renderPlaceholderCard());
+  }
+  lines.push('</div>');
+
+  // ── TODO: aggregation metrics ──────────────────────────────────────
+  lines.push('');
+  lines.push('{/* TODO: add aggregation metrics (averages / sums / time series)');
+  lines.push('    by adding backend endpoints and per-metric hooks. Wire them in');
+  lines.push('    alongside the count cards above. */}');
+
+  // ── Recent-items preview ───────────────────────────────────────────
+  lines.push('');
+  lines.push('<div className="rounded-lg border border-gray-200 bg-white dark:border-gray-700 dark:bg-gray-900">');
+  lines.push('  <div className="border-b border-gray-200 dark:border-gray-700 px-6 py-3">');
+  lines.push('    <h3 className="text-sm font-semibold text-gray-700 dark:text-gray-200 uppercase tracking-wider">');
+  lines.push(`      Recent ${humanize(modelName)}s`);
+  lines.push('    </h3>');
+  lines.push('  </div>');
+
+  if (previewColumns.length === 0) {
+    lines.push('  <div className="px-6 py-4 text-sm text-gray-400">No displayable fields.</div>');
+  } else {
+    lines.push('  <table className="min-w-full divide-y divide-gray-200 dark:divide-gray-700">');
+    lines.push('    <thead>');
+    lines.push('      <tr>');
+    for (const col of previewColumns) {
+      lines.push(
+        `        <th className="px-6 py-3 text-left text-xs font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wider">` +
+        humanize(col) +
+        `</th>`
+      );
+    }
+    lines.push('      </tr>');
+    lines.push('    </thead>');
+    lines.push('    <tbody className="divide-y divide-gray-200 dark:divide-gray-700">');
+    lines.push('      {preview.map((item, idx) => (');
+    lines.push('        <tr');
+    lines.push('          key={idx}');
+    lines.push('          onClick={() => onSelect?.(item)}');
+    lines.push('          className="hover:bg-gray-50 dark:hover:bg-gray-800 cursor-pointer"');
+    lines.push('        >');
+    for (const col of previewColumns) {
+      lines.push(
+        `          <td className="px-6 py-4 text-sm text-gray-700 dark:text-gray-300">` +
+        `{String((item as any).${col} ?? '')}</td>`
+      );
+    }
+    lines.push('        </tr>');
+    lines.push('      ))}');
+    lines.push('      {preview.length === 0 && (');
+    lines.push(`        <tr><td colSpan={${previewColumns.length}} className="px-6 py-4 text-sm text-gray-400">No records yet.</td></tr>`);
+    lines.push('      )}');
+    lines.push('    </tbody>');
+    lines.push('  </table>');
+  }
+  lines.push('</div>');
+
+  return lines.join('\n');
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Card rendering
+// ──────────────────────────────────────────────────────────────────────
+
+function renderTotalCard(modelName: string): string[] {
+  const pluralLower = humanize(modelName).toLowerCase() + 's';
+  return [
+    '  <div className="rounded-lg border border-gray-200 bg-white p-6 shadow-sm dark:border-gray-700 dark:bg-gray-900">',
+    '    <p className="text-xs font-medium uppercase tracking-wide text-gray-500 dark:text-gray-400">',
+    `      Total ${pluralLower}`,
+    '    </p>',
+    '    <p className="mt-2 text-3xl font-semibold text-gray-900 dark:text-gray-100">',
+    '      {items.length}',
+    '    </p>',
+    '  </div>',
+  ];
+}
+
+function renderEnumBreakdownCard(field: EnumField): string[] {
+  // One card per enum value — shows count of records where the field
+  // equals that value.
+  const cards: string[] = [];
+  for (const value of field.values) {
+    cards.push(
+      '  <div className="rounded-lg border border-gray-200 bg-white p-6 shadow-sm dark:border-gray-700 dark:bg-gray-900">',
+      '    <p className="text-xs font-medium uppercase tracking-wide text-gray-500 dark:text-gray-400">',
+      `      ${humanize(field.name)}: ${humanize(value)}`,
+      '    </p>',
+      '    <p className="mt-2 text-3xl font-semibold text-gray-900 dark:text-gray-100">',
+      `      {items.filter((i: any) => i.${field.name} === ${JSON.stringify(value)}).length}`,
+      '    </p>',
+      '  </div>',
+    );
+  }
+  return cards;
+}
+
+function renderPlaceholderCard(): string[] {
+  return [
+    '  <div className="rounded-lg border border-dashed border-gray-300 p-6 text-sm text-gray-400 dark:border-gray-600">',
+    '    Add a metric here — e.g. a sum, average, or time-windowed count.',
+    '  </div>',
+  ];
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Field inference
+// ──────────────────────────────────────────────────────────────────────
+
+interface EnumField {
+  name: string;
+  values: string[];
+}
+
+function inferEnumFields(model: ModelSpec): EnumField[] {
+  const out: EnumField[] = [];
+  const attrs = model.attributes ?? {};
+  for (const [name, rawDef] of Object.entries(attrs)) {
+    const def = rawDef as { values?: string[] };
+    const values = def?.values;
+    if (Array.isArray(values) && values.length > 0 && values.length <= 6) {
+      out.push({ name, values });
+    }
+  }
+  // Cap: one enum breakdown in the card row to avoid card sprawl. The
+  // remaining enum fields stay available in the list view; users can
+  // promote more breakdowns manually.
+  return out.slice(0, 1);
+}
+
+function inferPreviewColumns(model: ModelSpec): string[] {
+  const attrs = model.attributes ?? {};
+  return Object.keys(attrs)
+    .filter(n => !METADATA_FIELD_NAMES.has(n))
+    .slice(0, 4);   // cap to keep the table readable
+}
+
+function humanize(name: string): string {
+  return name
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, c => c.toUpperCase())
+    .trim();
+}

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

@@ -0,0 +1,135 @@
+/**
+ * Detail-view body composer for ReactAppStarter
+ *
+ * Renders the interior of a detail view as a JSX-safe definition list:
+ * business fields first (prominent), metadata fields second (muted).
+ * The outer card + actions live in `skeletons/detail.tsx.template`.
+ *
+ * Unlike list view, the interior here is mostly label→value pairs, not
+ * a table. We use `<dl>` / `<dt>` / `<dd>` directly rather than routing
+ * through a specific atomic component — the field-list shape isn't one
+ * of the adapter's atomic components, and forcing it through a `card`
+ * adapter would add structure without clarifying anything in the
+ * generated code.
+ *
+ * BelongsTo relationships: today we emit the raw FK id. A future pass
+ * will resolve FK → entity display name (matches runtime's
+ * getEntityDisplayName). Marked with a TODO comment in the output so
+ * users inspecting the generated file see the hook.
+ */
+
+import { METADATA_FIELDS } from '@specverse/runtime/views/core';
+import type { EmitContext, ModelSpec } from './view-emitter.js';
+
+/**
+ * Metadata attribute names rendered in a muted style. Sourced from
+ * the canonical pattern library so both this composer and the rest
+ * of the system stay in sync automatically.
+ */
+const METADATA_FIELD_NAMES = new Set(METADATA_FIELDS);
+
+export function composeDetailBody(context: EmitContext): string {
+  const { business, metadata } = partitionFields(context.model);
+  const belongsTo = extractBelongsTo(context.model);
+
+  const lines: string[] = [];
+  lines.push('<div className="rounded-lg border border-gray-200 bg-white p-6 dark:border-gray-700 dark:bg-gray-900">');
+
+  if (business.length > 0) {
+    lines.push('  <dl className="grid grid-cols-1 gap-4 sm:grid-cols-2">');
+    for (const field of business) {
+      lines.push(...renderField(field, { muted: false }));
+    }
+    lines.push('  </dl>');
+  } else {
+    lines.push('  <p className="text-sm text-gray-400">No business fields defined for this model.</p>');
+  }
+
+  if (belongsTo.length > 0) {
+    lines.push('');
+    lines.push('  {/* TODO: resolve FK ids → related entity display names.');
+    lines.push('      See @specverse/runtime/views/core/entity-display for the');
+    lines.push('      canonical resolver, or load the related record in a hook. */}');
+    lines.push('  <dl className="mt-6 grid grid-cols-1 gap-4 sm:grid-cols-2 border-t border-gray-200 dark:border-gray-700 pt-4">');
+    for (const rel of belongsTo) {
+      lines.push(...renderField({ name: `${rel}Id`, label: humanize(rel) }, { muted: false }));
+    }
+    lines.push('  </dl>');
+  }
+
+  if (metadata.length > 0) {
+    lines.push('');
+    lines.push('  <dl className="mt-6 grid grid-cols-1 gap-2 sm:grid-cols-2 border-t border-gray-200 dark:border-gray-700 pt-4 text-xs text-gray-500 dark:text-gray-400">');
+    for (const field of metadata) {
+      lines.push(...renderField(field, { muted: true }));
+    }
+    lines.push('  </dl>');
+  }
+
+  lines.push('</div>');
+  return lines.join('\n');
+}
+
+interface Field {
+  name: string;
+  /** Display label; defaults to humanize(name). */
+  label?: string;
+}
+
+function partitionFields(model: ModelSpec): { business: Field[]; metadata: Field[] } {
+  const attrs = Object.keys(model.attributes ?? {});
+  const business: Field[] = [];
+  const metadata: Field[] = [];
+  for (const name of attrs) {
+    const field = { name, label: humanize(name) };
+    if (METADATA_FIELD_NAMES.has(name)) {
+      metadata.push(field);
+    } else {
+      business.push(field);
+    }
+  }
+  return { business, metadata };
+}
+
+/**
+ * Extract belongsTo relationship names from the model. Returns e.g.
+ * `['author']` for a Post that `belongsTo Author`. The skeleton's
+ * item already has `authorId` as a scalar field — we surface it
+ * explicitly in its own section so the generated UI separates "this
+ * entity's data" from "related entities."
+ */
+function extractBelongsTo(model: ModelSpec): string[] {
+  const rels = model.relationships ?? {};
+  const out: string[] = [];
+  for (const [name, def] of Object.entries(rels)) {
+    const d = def as { type?: string };
+    if (d?.type === 'belongsTo') out.push(name);
+  }
+  return out;
+}
+
+function renderField(field: Field, opts: { muted: boolean }): string[] {
+  const label = field.label ?? humanize(field.name);
+  const labelCls = opts.muted
+    ? 'font-medium uppercase tracking-wide text-gray-400 dark:text-gray-500'
+    : 'text-sm font-medium text-gray-500 dark:text-gray-400';
+  const valueCls = opts.muted
+    ? 'text-gray-500 dark:text-gray-400'
+    : 'mt-1 text-sm text-gray-900 dark:text-gray-100 break-words';
+
+  return [
+    '    <div>',
+    `      <dt className="${labelCls}">${label}</dt>`,
+    `      <dd className="${valueCls}">` +
+      `{String((item as any).${field.name} ?? '')}` +
+    '</dd>',
+    '    </div>',
+  ];
+}
+
+function humanize(name: string): string {
+  return name
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, c => c.toUpperCase())
+    .trim();
+}