@specverse/engines 4.1.30 → 4.2.1

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,49 @@
+/**
+ * {{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';
+{{RELATED_IMPORTS}}
+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();
+{{RELATED_HOOKS}}
+
+  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,96 @@
+/**
+ * {{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';
+{{RELATED_IMPORTS}}
+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();
+{{RELATED_HOOKS}}
+
+  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,116 @@
+/**
+ * {{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';
+{{RELATED_IMPORTS}}
+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();
+{{RELATED_HOOKS}}
+
+  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,74 @@
+/**
+ * {{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';
+{{RELATED_IMPORTS}}
+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();
+{{RELATED_HOOKS}}
+  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/use-api-hooks-starter-generator.ts

@@ -0,0 +1,124 @@
+/**
+ * useApi hooks generator for ReactAppStarter
+ *
+ * Emits typed per-model React Query hooks that the starter's view
+ * skeletons import directly (`useTasksQuery`, `useCreateTaskMutation`,
+ * etc.). All hooks hit the realized backend's REST endpoints under
+ * `/api/{resource}` via the sibling `apiClient` helper.
+ *
+ * Why a separate generator from the runtime one: ReactAppRuntime
+ * ships a generic `useEntitiesQuery(controller, model)` because its
+ * views are rendered by @specverse/runtime using runtime dispatch.
+ * The starter wants plain typed hooks the user can read and edit.
+ */
+
+/**
+ * Minimal English pluralizer. Matches the conventions used by
+ * view-emitter so the generated hooks pair cleanly with the generated
+ * view imports.
+ */
+function pluralize(s: string): string {
+  if (/y$/.test(s) && !/[aeiou]y$/.test(s)) return s.replace(/y$/, 'ies');
+  if (/(s|x|z|ch|sh)$/.test(s)) return s + 'es';
+  return s + 's';
+}
+
+export interface UseApiHooksStarterContext {
+  spec: {
+    models?: Record<string, any>;
+  };
+  manifest?: unknown;
+}
+
+export async function generate(context: UseApiHooksStarterContext): Promise<string> {
+  const models = Object.keys(context.spec.models ?? {});
+
+  const importsAndTypes = `/**
+ * useApi — typed per-model React Query hooks (ReactAppStarter)
+ *
+ * Safe to edit. Users who want to reshape their API client or add
+ * request/response interceptors should start here. Each hook calls
+ * the sibling \`apiClient\` which does the actual fetch; edit
+ * \`apiClient.ts\` to change transport concerns (headers, auth, etc.).
+ */
+
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+${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,
+  });
+  if (!res.ok) {
+    throw new Error(\`\${res.status} \${res.statusText} — \${url}\`);
+  }
+  if (res.status === 204) return undefined as T;
+  return (await res.json()) as T;
+}
+`;
+
+  const hookBlocks = models.map(m => generateModelHooks(m)).join('\n\n');
+
+  return importsAndTypes + '\n' + hookBlocks + '\n';
+}
+
+function generateModelHooks(model: string): string {
+  const plural = pluralize(model);
+  const resource = plural.toLowerCase();
+  const modelLower = model.toLowerCase();
+
+  return `// ─── ${model} ───────────────────────────────────────────────────
+
+export function use${plural}Query() {
+  return useQuery({
+    queryKey: ['${resource}'],
+    queryFn: () => fetchJSON<${model}[]>(\`\${API_BASE}/api/${resource}\`),
+  });
+}
+
+export function use${model}Query(id: string | number | undefined) {
+  return useQuery({
+    queryKey: ['${resource}', id],
+    queryFn: () => fetchJSON<${model}>(\`\${API_BASE}/api/${resource}/\${id}\`),
+    enabled: id !== undefined && id !== null,
+  });
+}
+
+export function useCreate${model}Mutation() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (data: Partial<${model}>) =>
+      fetchJSON<${model}>(\`\${API_BASE}/api/${resource}\`, {
+        method: 'POST',
+        body: JSON.stringify(data),
+      }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['${resource}'] }),
+  });
+}
+
+export function useUpdate${model}Mutation() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string | number; data: Partial<${model}> }) =>
+      fetchJSON<${model}>(\`\${API_BASE}/api/${resource}/\${id}\`, {
+        method: 'PATCH',
+        body: JSON.stringify(data),
+      }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['${resource}'] }),
+  });
+}
+
+export function useDelete${model}Mutation() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (id: string | number) =>
+      fetchJSON<void>(\`\${API_BASE}/api/${resource}/\${id}\`, { method: 'DELETE' }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['${resource}'] }),
+  });
+}`;
+}
+
+export default generate;