@specverse/engines 4.1.28 → 4.2.0

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

@@ -0,0 +1,157 @@
+/**
+ * Regeneration safety for ReactAppStarter
+ *
+ * When realize runs Factory B, generated files can end up in two states:
+ *
+ *  1. Pristine — the file on disk is byte-identical to what we last
+ *     wrote. Safe to overwrite with a new version.
+ *
+ *  2. User-edited — the user modified the file. We must NOT clobber
+ *     their work.
+ *
+ * The mechanism is an SHA-256 hash recorded per file in
+ * `.specverse-gen/hashes.json` at write time. At regeneration, we
+ * compare the on-disk hash against the recorded one. Mismatch → skip
+ * with a warning. Match → overwrite and update the hash.
+ *
+ * The factory orchestrator wraps realize's write calls through
+ * `reconcileWrites` below, which handles all three outcomes:
+ *  - brand-new file → write, record hash
+ *  - pristine existing → overwrite, update hash
+ *  - user-edited existing → skip, leave hash unchanged
+ */
+
+import { createHash } from 'crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, relative } from 'path';
+
+/** Relative path (from project root) → SHA-256 hex digest. */
+export type HashManifest = Record<string, string>;
+
+export const HASHES_DIR = '.specverse-gen';
+export const HASHES_FILE = 'hashes.json';
+
+export function sha256(s: string): string {
+  return createHash('sha256').update(s, 'utf8').digest('hex');
+}
+
+/**
+ * Load a `.specverse-gen/hashes.json` from the project root. Returns
+ * an empty manifest if the file is missing or malformed — the
+ * calling convention is that a missing manifest means "no record of
+ * prior generation, treat everything as new."
+ */
+export function loadHashManifest(projectRoot: string): HashManifest {
+  const path = join(projectRoot, HASHES_DIR, HASHES_FILE);
+  if (!existsSync(path)) return {};
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      const out: HashManifest = {};
+      for (const [k, v] of Object.entries(parsed)) {
+        if (typeof v === 'string') out[k] = v;
+      }
+      return out;
+    }
+  } catch {
+    // Malformed — treat as missing. Next generate pass will overwrite.
+  }
+  return {};
+}
+
+/** Write the manifest back to `.specverse-gen/hashes.json`. */
+export function saveHashManifest(projectRoot: string, manifest: HashManifest): void {
+  const dir = join(projectRoot, HASHES_DIR);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, HASHES_FILE);
+  writeFileSync(path, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+}
+
+export interface ReconcileResult {
+  /** Relative path → content for every file approved for writing. */
+  approvedWrites: Record<string, string>;
+  /** Files we skipped because the user edited them (or couldn't confirm origin). */
+  skipped: { path: string; reason: string }[];
+  /** The updated hash manifest reflecting all approved writes. */
+  manifest: HashManifest;
+}
+
+/**
+ * Pure-planning triage. For each proposed file, decides whether the
+ * write is safe:
+ *  - Path doesn't exist → APPROVE, record hash.
+ *  - Path exists + on-disk hash matches recorded hash → APPROVE
+ *    (pristine overwrite), update hash.
+ *  - Path exists + hash mismatch → SKIP (user-edited), preserve old
+ *    hash record.
+ *  - Path exists + no recorded hash → SKIP (cautious default).
+ *
+ * Reads the filesystem but doesn't write. Returns the approved writes
+ * as a map the caller can pass to the realize write pipeline.
+ */
+export function reconcileWrites(
+  projectRoot: string,
+  proposed: Record<string, string>,
+  prevManifest: HashManifest
+): ReconcileResult {
+  const manifest: HashManifest = { ...prevManifest };
+  const approvedWrites: Record<string, string> = {};
+  const skipped: { path: string; reason: string }[] = [];
+
+  for (const [relPath, content] of Object.entries(proposed)) {
+    const abs = join(projectRoot, relPath);
+    const newHash = sha256(content);
+
+    if (!existsSync(abs)) {
+      approvedWrites[relPath] = content;
+      manifest[relPath] = newHash;
+      continue;
+    }
+
+    const currentContent = readFileSync(abs, 'utf8');
+    const currentHash = sha256(currentContent);
+    const recordedHash = prevManifest[relPath];
+
+    if (recordedHash == null) {
+      skipped.push({
+        path: relPath,
+        reason: 'no prior hash recorded — cannot confirm this file was generated by us',
+      });
+      continue;
+    }
+
+    if (currentHash === recordedHash) {
+      approvedWrites[relPath] = content;
+      manifest[relPath] = newHash;
+      continue;
+    }
+
+    skipped.push({
+      path: relPath,
+      reason: 'file has been edited since last generation',
+    });
+  }
+
+  return { approvedWrites, skipped, manifest };
+}
+
+/**
+ * Human-readable summary of a ReconcileResult. Used by the factory
+ * orchestrator to log after a run.
+ */
+export function summarize(result: ReconcileResult, projectRoot: string): string {
+  const lines: string[] = [];
+  const writeCount = Object.keys(result.approvedWrites).length;
+  lines.push(`[ReactAppStarter] Approved ${writeCount} file(s) for writing.`);
+  if (result.skipped.length > 0) {
+    lines.push(`[ReactAppStarter] Skipped ${result.skipped.length} user-edited file(s):`);
+    for (const { path, reason } of result.skipped) {
+      lines.push(`  - ${path} (${reason})`);
+    }
+    lines.push(
+      `To accept upstream regeneration for a skipped file, delete it (\`rm ${relative(process.cwd(), projectRoot)}/PATH\`) and re-run \`spv realize\`.`
+    );
+  }
+  return lines.join('\n');
+}

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

@@ -0,0 +1,47 @@
+/**
+ * {{MODEL_NAME}}DashboardView — 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`.
+ *
+ * A minimal dashboard: summary counts derived from the list query,
+ * plus a compact preview of recent records. Charts and aggregation
+ * metrics are deferred — add them as the backend grows suitable
+ * endpoints.
+ */
+import { useMemo } from 'react';
+import { use{{PLURAL_MODEL}}Query } from '../hooks/useApi';
+import type { {{MODEL_NAME}} } from '../types/api';
+
+interface {{MODEL_NAME}}DashboardViewProps {
+  /** Number of recent records to preview. Default 5. */
+  previewLimit?: number;
+  onSelect?: (item: {{MODEL_NAME}}) => void;
+}
+
+export function {{MODEL_NAME}}DashboardView({
+  previewLimit = 5,
+  onSelect,
+}: {{MODEL_NAME}}DashboardViewProps) {
+  const { data: items = [], isLoading, error } = use{{PLURAL_MODEL}}Query();
+
+  const preview = useMemo(
+    () => items.slice(0, previewLimit),
+    [items, previewLimit]
+  );
+
+  if (isLoading) return <div className="p-4 text-gray-500">Loading dashboard…</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-6">
+      <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100">
+        {{MODEL_NAME}} dashboard
+      </h2>
+
+      {/* Pattern-rendered dashboard body (metrics + preview). Edit freely. */}
+      {{BODY}}
+    </div>
+  );
+}

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

@@ -0,0 +1,94 @@
+/**
+ * {{MODEL_NAME}}DetailView — 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 { use{{PLURAL_MODEL}}Query, useDelete{{MODEL_NAME}}Mutation } from '../hooks/useApi';
+import type { {{MODEL_NAME}} } from '../types/api';
+
+interface {{MODEL_NAME}}DetailViewProps {
+  entityId: string | number;
+  onEdit?: (item: {{MODEL_NAME}}) => void;
+  onBack?: () => void;
+  /** Called after the delete mutation succeeds. */
+  onDeleted?: () => void;
+}
+
+export function {{MODEL_NAME}}DetailView({
+  entityId,
+  onEdit,
+  onBack,
+  onDeleted,
+}: {{MODEL_NAME}}DetailViewProps) {
+  const { data: items = [], isLoading, error } = use{{PLURAL_MODEL}}Query();
+  const deleteItem = useDelete{{MODEL_NAME}}Mutation();
+
+  const item = items.find(
+    (x: {{MODEL_NAME}}) => (x as any).id === entityId
+  );
+
+  if (isLoading) return <div className="p-4 text-gray-500">Loading…</div>;
+  if (error) return <div className="p-4 text-red-600">Error loading {{PLURAL_LOWER}}: {String(error)}</div>;
+  if (!item) return <div className="p-4 text-gray-400">No {{SINGULAR_LOWER}} matching id {String(entityId)}.</div>;
+
+  const handleDelete = async () => {
+    if (!confirm('Delete this {{SINGULAR_LOWER}}?')) return;
+    try {
+      await deleteItem.mutateAsync((item as any).id);
+      onDeleted?.();
+    } catch {
+      // deleteItem.error is surfaced below
+    }
+  };
+
+  return (
+    <div className="p-6 space-y-4">
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          {onBack && (
+            <button
+              type="button"
+              onClick={onBack}
+              className="text-sm text-gray-500 hover:text-gray-700"
+            >
+              ← Back
+            </button>
+          )}
+          <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100">
+            {{MODEL_NAME}} detail
+          </h2>
+        </div>
+        <div className="flex gap-2">
+          {onEdit && (
+            <button
+              type="button"
+              onClick={() => onEdit(item)}
+              className="rounded bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700"
+            >
+              Edit
+            </button>
+          )}
+          <button
+            type="button"
+            onClick={handleDelete}
+            disabled={deleteItem.isPending}
+            className="rounded bg-red-600 px-4 py-2 text-sm font-medium text-white hover:bg-red-700 disabled:opacity-60"
+          >
+            {deleteItem.isPending ? 'Deleting…' : 'Delete'}
+          </button>
+        </div>
+      </div>
+
+      {/* Pattern-rendered detail body (fields). Edit freely. */}
+      {{BODY}}
+
+      {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/skeletons/form.tsx.template

@@ -0,0 +1,114 @@
+/**
+ * {{MODEL_NAME}}FormView — 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`.
+ *
+ * Controlled form. One field per non-auto-generated attribute.
+ * Mode: 'create' (default) or 'update' — passed as a prop.
+ */
+import { useEffect, useState } from 'react';
+import {
+  use{{PLURAL_MODEL}}Query,
+  useCreate{{MODEL_NAME}}Mutation,
+  useUpdate{{MODEL_NAME}}Mutation,
+} from '../hooks/useApi';
+import type { {{MODEL_NAME}} } from '../types/api';
+
+type FormMode = 'create' | 'update';
+
+interface {{MODEL_NAME}}FormViewProps {
+  mode?: FormMode;
+  /** Required in update mode. */
+  entityId?: string | number;
+  onSuccess?: (item: {{MODEL_NAME}}) => void;
+  onCancel?: () => void;
+}
+
+export function {{MODEL_NAME}}FormView({
+  mode = 'create',
+  entityId,
+  onSuccess,
+  onCancel,
+}: {{MODEL_NAME}}FormViewProps) {
+  const { data: items = [] } = use{{PLURAL_MODEL}}Query();
+  const createItem = useCreate{{MODEL_NAME}}Mutation();
+  const updateItem = useUpdate{{MODEL_NAME}}Mutation();
+
+  const existing =
+    mode === 'update'
+      ? items.find((x: {{MODEL_NAME}}) => (x as any).id === entityId)
+      : undefined;
+
+  const [formData, setFormData] = useState<Partial<{{MODEL_NAME}}>>(existing ?? {});
+
+  // When the fetched list lands after initial render (update mode),
+  // hydrate the form with the loaded entity's data.
+  useEffect(() => {
+    if (existing) setFormData(existing);
+  }, [existing]);
+
+  const handleChange = (field: string, value: unknown) => {
+    setFormData(prev => ({ ...prev, [field]: value }) as Partial<{{MODEL_NAME}}>);
+  };
+
+  const handleSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    try {
+      const result =
+        mode === 'create'
+          ? await createItem.mutateAsync(formData as {{MODEL_NAME}})
+          : await updateItem.mutateAsync({
+              id: entityId as any,
+              data: formData as Partial<{{MODEL_NAME}}>,
+            });
+      onSuccess?.(result as {{MODEL_NAME}});
+    } catch {
+      // Mutation errors are surfaced below via createItem / updateItem.
+    }
+  };
+
+  const mutation = mode === 'create' ? createItem : updateItem;
+  const submitLabel =
+    mode === 'create'
+      ? mutation.isPending ? 'Creating…' : 'Create {{MODEL_NAME}}'
+      : mutation.isPending ? 'Updating…' : 'Update {{MODEL_NAME}}';
+
+  return (
+    <form onSubmit={handleSubmit} className="p-6 space-y-6">
+      <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100">
+        {mode === 'create' ? 'New {{MODEL_NAME}}' : 'Edit {{MODEL_NAME}}'}
+      </h2>
+
+      {/* Pattern-rendered form fields. Edit freely. */}
+      {{BODY}}
+
+      <div className="flex gap-2 border-t border-gray-200 dark:border-gray-700 pt-4">
+        <button
+          type="submit"
+          disabled={mutation.isPending}
+          className="rounded bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700 disabled:opacity-60"
+        >
+          {submitLabel}
+        </button>
+        {onCancel && (
+          <button
+            type="button"
+            onClick={onCancel}
+            className="rounded border border-gray-300 px-4 py-2 text-sm font-medium text-gray-700 hover:bg-gray-50 dark:border-gray-600 dark:text-gray-200 dark:hover:bg-gray-800"
+          >
+            Cancel
+          </button>
+        )}
+      </div>
+
+      {mutation.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">
+          {mode === 'create' ? 'Create failed: ' : 'Update failed: '}
+          {String(mutation.error)}
+        </div>
+      )}
+    </form>
+  );
+}

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';
+}