@specverse/engines 4.1.30 → 4.2.1

package/libs/instance-factories/applications/templates/react-starter/html-to-jsx.ts

@@ -0,0 +1,334 @@
+/**
+ * HTML → JSX transformer for ReactAppStarter
+ *
+ * Input: HTML strings produced by the canonical Tailwind adapter
+ * (`@specverse/runtime/views/tailwind`). Output: JSX-safe source
+ * that can be dropped between JSX tags in a .tsx template.
+ *
+ * Scope is deliberately narrow:
+ *  - Controlled input — only the adapter's output shape matters.
+ *  - String transformer with a small tokenizer, not a full HTML parser.
+ *  - No SVG / MathML / script / style tags.
+ *
+ * If the adapter ever produces markup outside this scope, extend the
+ * ATTRIBUTE_RENAMES map / VOID_ELEMENTS set + add a focused test,
+ * don't broaden the tokenizer into a general HTML parser.
+ *
+ * See: README.md ("The html-to-jsx transformer — scope").
+ */
+
+/**
+ * HTML void elements — must be self-closing in JSX.
+ */
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img',
+  'input', 'link', 'meta', 'source', 'track', 'wbr',
+]);
+
+/**
+ * HTML attribute → JSX attribute renames. JSX is case-sensitive and
+ * camelCases several HTML attribute names. Only lists the ones the
+ * Tailwind adapter actually emits.
+ */
+const ATTRIBUTE_RENAMES: Record<string, string> = {
+  class: 'className',
+  for: 'htmlFor',
+  tabindex: 'tabIndex',
+  readonly: 'readOnly',
+  maxlength: 'maxLength',
+  minlength: 'minLength',
+  colspan: 'colSpan',
+  rowspan: 'rowSpan',
+  autofocus: 'autoFocus',
+  autocomplete: 'autoComplete',
+  cellpadding: 'cellPadding',
+  cellspacing: 'cellSpacing',
+  enctype: 'encType',
+  usemap: 'useMap',
+  accesskey: 'accessKey',
+  contenteditable: 'contentEditable',
+  spellcheck: 'spellCheck',
+  crossorigin: 'crossOrigin',
+  srcset: 'srcSet',
+  srcdoc: 'srcDoc',
+};
+
+/**
+ * Convert an HTML string to JSX-safe source.
+ *
+ * Idempotent on already-JSX-shaped input.
+ */
+export function htmlToJsx(html: string): string {
+  if (!html) return '';
+
+  const tokens = tokenize(html);
+  return tokens.map(transformToken).join('');
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Tokenizer
+// ──────────────────────────────────────────────────────────────────────
+
+type Token =
+  | { kind: 'text'; value: string }
+  | { kind: 'tag'; raw: string; tagName: string; isClosing: boolean; isSelfClosed: boolean };
+
+/**
+ * Split an HTML string into text and tag tokens. Quoted attribute
+ * values never close a tag, even if they contain '>'. The adapter
+ * does not emit unbalanced quotes, so a simple state machine is
+ * sufficient.
+ */
+function tokenize(input: string): Token[] {
+  const tokens: Token[] = [];
+  let i = 0;
+  const n = input.length;
+
+  while (i < n) {
+    const ch = input[i];
+    if (ch === '<') {
+      // Start of tag. Consume until the matching '>', respecting quotes.
+      const tagStart = i;
+      i++; // consume '<'
+
+      let quote: '"' | "'" | null = null;
+      while (i < n) {
+        const c = input[i];
+        if (quote) {
+          if (c === quote) quote = null;
+          i++;
+          continue;
+        }
+        if (c === '"' || c === "'") {
+          quote = c;
+          i++;
+          continue;
+        }
+        if (c === '>') {
+          i++; // include the '>'
+          break;
+        }
+        i++;
+      }
+
+      const raw = input.slice(tagStart, i);
+      const isClosing = raw.startsWith('</');
+      const isSelfClosed = raw.endsWith('/>');
+      const tagName = parseTagName(raw);
+      tokens.push({ kind: 'tag', raw, tagName, isClosing, isSelfClosed });
+    } else {
+      // Text until the next '<'.
+      const textStart = i;
+      while (i < n && input[i] !== '<') i++;
+      tokens.push({ kind: 'text', value: input.slice(textStart, i) });
+    }
+  }
+
+  return tokens;
+}
+
+function parseTagName(tagRaw: string): string {
+  // Handles '<foo', '</foo', '<foo ', '<foo/>', '<foo>' etc.
+  const m = tagRaw.match(/^<\/?([a-zA-Z][a-zA-Z0-9-]*)/);
+  return m ? m[1].toLowerCase() : '';
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Transformation
+// ──────────────────────────────────────────────────────────────────────
+
+function transformToken(token: Token): string {
+  if (token.kind === 'text') {
+    // Adapter output never contains raw '{' or '}' in text nodes in
+    // the current implementation. If that changes, escape them here
+    // via `{'{'}` / `{'}'}`. Flagged for future: a regression test
+    // in view-emitter.test.ts that feeds a spec containing literal
+    // braces and expects them round-tripped.
+    return token.value;
+  }
+
+  return transformTag(token.raw, token.tagName, token.isClosing, token.isSelfClosed);
+}
+
+/**
+ * Transform a single tag: rename attributes, self-close if void.
+ *
+ * Works inside-out: split into `<`, open-portion, attributes, close-portion, `>`.
+ * We only rewrite attribute NAMES (identifier tokens at attribute start),
+ * never attribute values or text. The tokenizer guarantees we see the
+ * full tag as one unit.
+ */
+function transformTag(
+  raw: string,
+  tagName: string,
+  isClosing: boolean,
+  isSelfClosed: boolean
+): string {
+  if (isClosing) {
+    // '</div>' — nothing to rewrite
+    return raw;
+  }
+
+  // Split the tag into the tag-name section and the attributes section.
+  // Strip the leading '<' and trailing '>' or '/>'.
+  const inner = isSelfClosed
+    ? raw.slice(1, -2).trimEnd()
+    : raw.slice(1, -1);
+
+  // Separate tag name from attributes. The tag name is the first word.
+  const nameMatch = inner.match(/^([a-zA-Z][a-zA-Z0-9-]*)(.*)$/s);
+  if (!nameMatch) return raw;
+
+  const elementName = nameMatch[1];
+  const attrsSection = nameMatch[2];
+
+  // Parse attributes into structured form, rename names, re-serialise.
+  // This guarantees we never rewrite anything inside an attribute value.
+  const attrs = parseAttributes(attrsSection);
+  const renamedAttrs = attrs.map(renameAttribute);
+  const rebuiltAttrs = serializeAttributes(renamedAttrs);
+
+  const shouldSelfClose = VOID_ELEMENTS.has(tagName) && !isSelfClosed;
+
+  if (shouldSelfClose || isSelfClosed) {
+    return `<${elementName}${rebuiltAttrs} />`;
+  }
+  return `<${elementName}${rebuiltAttrs}>`;
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Attribute tokenizer
+// ──────────────────────────────────────────────────────────────────────
+
+interface Attribute {
+  name: string;
+  /** undefined = boolean attribute, no value. */
+  value?: string;
+  /** How the original source quoted the value — preserve on output. */
+  quote?: '"' | "'";
+}
+
+/**
+ * Parse the attributes section of a tag (the substring after the tag
+ * name, before the closing `>` or `/>`) into a list of attributes.
+ * Whitespace is consumed between attributes; values inside quotes are
+ * opaque.
+ */
+function parseAttributes(section: string): Attribute[] {
+  const attrs: Attribute[] = [];
+  let i = 0;
+  const n = section.length;
+
+  while (i < n) {
+    // Skip whitespace
+    while (i < n && /\s/.test(section[i])) i++;
+    if (i >= n) break;
+
+    // Read name (letters, digits, hyphens, colons for namespaced attrs)
+    const nameStart = i;
+    while (i < n && /[a-zA-Z0-9:_-]/.test(section[i])) i++;
+    if (i === nameStart) {
+      // Nothing we recognise — advance to avoid infinite loop
+      i++;
+      continue;
+    }
+    const name = section.slice(nameStart, i);
+
+    // Look for '=value' or end-of-attr
+    // Skip whitespace before '='
+    let j = i;
+    while (j < n && /\s/.test(section[j])) j++;
+    if (j >= n || section[j] !== '=') {
+      // Boolean attribute (e.g. `readonly`, `disabled`)
+      attrs.push({ name });
+      continue;
+    }
+    // Consume '=' and optional whitespace
+    i = j + 1;
+    while (i < n && /\s/.test(section[i])) i++;
+    if (i >= n) {
+      // Malformed: attribute with '=' and no value. Treat as boolean.
+      attrs.push({ name });
+      break;
+    }
+
+    // Read value — quoted or unquoted
+    const vc = section[i];
+    if (vc === '"' || vc === "'") {
+      const quote = vc as '"' | "'";
+      i++; // skip opening quote
+      const valStart = i;
+      while (i < n && section[i] !== quote) i++;
+      const value = section.slice(valStart, i);
+      if (i < n) i++; // skip closing quote
+      attrs.push({ name, value, quote });
+    } else {
+      // Unquoted value — run until whitespace or '/' or '>'
+      const valStart = i;
+      while (i < n && !/[\s/>]/.test(section[i])) i++;
+      const value = section.slice(valStart, i);
+      attrs.push({ name, value });
+    }
+  }
+
+  return attrs;
+}
+
+/** Apply HTML→JSX name rewrite and, for `style`, value conversion. */
+function renameAttribute(attr: Attribute): Attribute {
+  const lower = attr.name.toLowerCase();
+  const newName = ATTRIBUTE_RENAMES[lower] ?? attr.name;
+
+  if (lower === 'style' && attr.value !== undefined) {
+    return { name: newName, value: cssStringToJsxObject(attr.value), quote: undefined };
+  }
+
+  return { ...attr, name: newName };
+}
+
+/**
+ * Serialise a list of attributes back into source form. Preserves the
+ * original quote style. A value of `{{ ... }}` (already a JSX object
+ * expression) is emitted unquoted (no surrounding `"`); it's already
+ * valid JSX syntax.
+ */
+function serializeAttributes(attrs: Attribute[]): string {
+  if (attrs.length === 0) return '';
+  const parts = attrs.map(attr => {
+    if (attr.value === undefined) return ` ${attr.name}`;
+    if (attr.value.startsWith('{{') && attr.value.endsWith('}}')) {
+      // JSX expression like {{ color: 'red' }} — no quotes.
+      return ` ${attr.name}=${attr.value}`;
+    }
+    const q = attr.quote ?? '"';
+    return ` ${attr.name}=${q}${attr.value}${q}`;
+  });
+  return parts.join('');
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// CSS → JSX style object
+// ──────────────────────────────────────────────────────────────────────
+
+function cssStringToJsxObject(css: string): string {
+  const declarations = css
+    .split(';')
+    .map(d => d.trim())
+    .filter(d => d.length > 0);
+
+  if (declarations.length === 0) return '{{}}';
+
+  const entries = declarations
+    .map(decl => {
+      const colonIdx = decl.indexOf(':');
+      if (colonIdx === -1) return null;
+      const prop = decl.slice(0, colonIdx).trim();
+      const value = decl.slice(colonIdx + 1).trim();
+      const camelProp = prop.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+      const escapedValue = value.replace(/'/g, "\\'");
+      return `${camelProp}: '${escapedValue}'`;
+    })
+    .filter((e): e is string => e !== null);
+
+  return `{{ ${entries.join(', ')} }}`;
+}

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

@@ -0,0 +1,146 @@
+/**
+ * List-view body composer for ReactAppStarter
+ *
+ * Implements the `renderBody` contract of view-emitter.ts for list
+ * views. Uses the canonical Tailwind adapter from
+ * `@specverse/runtime/views/tailwind` to render the TABLE SHELL, then
+ * injects a JSX `.map()` expression into the tbody so the generated
+ * component renders rows from the `filtered` array defined by the
+ * skeleton.
+ *
+ * Why split it this way: the adapter produces static HTML (the same
+ * HTML app-demo uses). For Factory B we want React that maps over
+ * runtime data — so we take the adapter's shell and replace a sentinel
+ * inside the tbody with a `{filtered.map(...)}` expression. The shell
+ * stays canonical; only the row-iteration JSX is synthesized here.
+ *
+ * See README.md for the full architecture.
+ */
+
+import { createUniversalTailwindAdapter } from '@specverse/runtime/views/tailwind';
+import { inferFieldsFromSchema } from '@specverse/runtime/views/core';
+import { htmlToJsx } from './html-to-jsx.js';
+import type { EmitContext, ModelSpec } from './view-emitter.js';
+import { buildFKMap } from './belongs-to.js';
+
+/**
+ * Sentinel token. Must be ASCII-safe (no curly braces) so it survives
+ * the html-to-jsx transform unchanged, and must be unique enough not
+ * to appear in real HTML output.
+ */
+const TBODY_SENTINEL = '__SPECVERSE_TBODY_ROWS__';
+
+/**
+ * Compose the list view's body as JSX-safe source. Returned string is
+ * meant to be dropped at `{{BODY}}` inside `skeletons/list.tsx.template`.
+ */
+export function composeListBody(context: EmitContext): string {
+  const fkMap = buildFKMap(context.model);
+  // Inference (`inferFieldsFromSchema`) reads attributes and doesn't
+  // see belongsTo relationships. For list views we want a column per
+  // belongsTo so users can scan "who owns this" at a glance —
+  // otherwise a Task table hides its Project and Assignee columns.
+  // Append any FK columns the inference missed, preserving order.
+  const inferred = inferColumns(context);
+  const inferredSet = new Set(inferred);
+  const extraFKs = [...fkMap.keys()].filter(k => !inferredSet.has(k));
+  const columns = [...inferred, ...extraFKs];
+
+  // Header label for an FK column should use the relationship name
+  // ("Owner") not the raw column name ("Owner Id"). The cell rendering
+  // in buildRowMap applies the matching FK→name resolution.
+  const headers = columns.map(col => {
+    const fk = fkMap.get(col);
+    return humanize(fk ? fk.name : col);
+  });
+
+  const adapter = createUniversalTailwindAdapter({ darkMode: true });
+  const shellHtml = adapter.components.table.render({
+    properties: { columns: headers },
+    children: TBODY_SENTINEL,
+  });
+
+  // Transform the static HTML shell to JSX-safe source. The sentinel
+  // lands in a text position inside the <tbody> and survives the
+  // transform untouched.
+  const shellJsx = htmlToJsx(shellHtml);
+
+  // Build the row-iteration JSX that replaces the sentinel. The
+  // skeleton's useMemo produces `filtered: Model[]`, so the map
+  // expression binds over that. onSelect is a prop the skeleton
+  // declares. Delete action wires to the deleteItem mutation.
+  const rowMap = buildRowMap(columns, fkMap);
+
+  if (!shellJsx.includes(TBODY_SENTINEL)) {
+    // Defensive: catches adapter output changes that no longer flow
+    // `children` into the tbody. Caught at composer time, not runtime.
+    throw new Error(
+      'composeListBody: tbody sentinel not present in adapter output. ' +
+      'The canonical Tailwind adapter may have changed its table rendering.'
+    );
+  }
+
+  return shellJsx.replace(TBODY_SENTINEL, rowMap);
+}
+
+/**
+ * Select the non-metadata attributes of a model. Delegates to the
+ * canonical pattern library so the column set is identical to what
+ * the runtime React adapter picks for the same model — parity test P3
+ * relies on this being one-and-the-same function.
+ */
+function inferColumns(context: EmitContext): string[] {
+  return inferFieldsFromSchema(context.modelSchemas, context.model.name);
+}
+
+/**
+ * Convert a camelCase attribute name to Title-Case words for display
+ * as a column header. Matches the convention used by runtime's
+ * pattern adapter (see `humanize` in runtime react-pattern-adapter).
+ */
+function humanize(name: string): string {
+  return name
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, c => c.toUpperCase())
+    .trim();
+}
+
+/**
+ * Emit the `{filtered.map(...)}` JSX expression that renders each
+ * row. Keep the output readable so users inspecting the generated
+ * file can follow what's happening.
+ */
+function buildRowMap(columns: string[], fkMap: Map<string, { name: string; target: string }>): string {
+  // Type-cast to `any` to avoid TS generic syntax (`<string, unknown>`)
+  // inside JSX expressions, which the TSX parser can't always
+  // disambiguate from a JSX opening tag. `any` is the right choice for
+  // starter-kit output anyway — the user will often reshape the row
+  // type after editing.
+  //
+  // FK columns render through `resolveEntityDisplayName(id, options)`
+  // so the user sees a name instead of a UUID. The options array
+  // (`${relName}Options`) is populated by the hook call wired into
+  // the list skeleton via view-emitter's RELATED_HOOKS substitution.
+  const cells = columns
+    .map(col => {
+      const fk = fkMap.get(col);
+      const expr = fk
+        ? `{resolveEntityDisplayName((item as any).${col}, ${fk.name}Options)}`
+        : `{String((item as any).${col} ?? '')}`;
+      return `            <td className="px-6 py-4 text-sm text-gray-700 dark:text-gray-300">` +
+        `${expr}</td>`;
+    })
+    .join('\n');
+
+  return [
+    '{filtered.map((item, idx) => (',
+    '  <tr',
+    '    key={idx}',
+    '    onClick={() => onSelect?.(item)}',
+    '    className="hover:bg-gray-50 dark:hover:bg-gray-800 cursor-pointer"',
+    '  >',
+    cells,
+    '  </tr>',
+    '))}',
+  ].join('\n');
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Factory B top-level orchestrator
+ *
+ * Single entry point the realize engine calls. Returns a map of
+ * `relativePath → content` for every file the factory decides to
+ * write, after applying regeneration-safety triage. Realize handles
+ * the actual filesystem writes via its normal multi-file generator
+ * pipeline.
+ *
+ * Skipped (user-edited) files are NOT in the returned map — realize
+ * never sees them, so user edits are safe. The hash manifest is
+ * emitted as one of the returned files (`.specverse-gen/hashes.json`)
+ * so it rolls through the same write pipeline.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { generate as generateViews } from './views-generator.js';
+import { generate as generateAppTsx } from './app-tsx-generator.js';
+import { generate as generatePackageJson } from './package-json-generator.js';
+import {
+  loadHashManifest,
+  reconcileWrites,
+  summarize,
+  HASHES_DIR,
+  HASHES_FILE,
+} from './regen-safety.js';
+import type { ExpandedSpec } from './views-generator.js';
+
+/**
+ * Context shape as it arrives from realize's code-generator. The
+ * generator protocol is "function receives context, returns string
+ * (the single file contents)". This orchestrator is special: instead
+ * of one file, it produces many (views × models, App.tsx,
+ * package.json, regen-safety manifest). It writes them directly and
+ * returns '' so realize's write pipeline skips the no-op.
+ *
+ * `outputDir` and `frontendDir` come from the realize-time context.
+ * `frontendDir` may be '.' for standalone layouts or 'frontend' for
+ * monorepos — either way, the resolved write root is
+ * `outputDir + frontendDir`.
+ */
+export interface OrchestratorContext {
+  spec: ExpandedSpec & { metadata?: { name?: string }; name?: string };
+  outputDir: string;
+  frontendDir?: string;
+  manifest?: unknown;
+}
+
+/**
+ * Produce the complete file set for a Factory B run, writing each
+ * file directly. Returns '' so the caller's single-file writeOutput
+ * short-circuits.
+ */
+export async function generate(context: OrchestratorContext): Promise<string> {
+  const { spec, outputDir } = context;
+  const frontendDir = context.frontendDir || 'frontend';
+  const projectRoot = frontendDir === '.' ? outputDir : join(outputDir, frontendDir);
+
+  // 1. Produce all file contents (pure composition — no I/O yet).
+  const proposed: Record<string, string> = {};
+
+  const viewFiles = await generateViews({ spec });
+  Object.assign(proposed, viewFiles);
+
+  proposed['src/App.tsx'] = await generateAppTsx({ spec });
+  proposed['package.json'] = await generatePackageJson({ spec });
+
+  // 2. Content-hashing triage against the prior manifest. Read-only.
+  const prevManifest = loadHashManifest(projectRoot);
+  const result = reconcileWrites(projectRoot, proposed, prevManifest);
+
+  // 3. Log the summary for operator visibility.
+  console.log(summarize(result, projectRoot));
+
+  // 4. Write the approved files + the updated hash manifest.
+  const toWrite: Record<string, string> = {
+    ...result.approvedWrites,
+    [`${HASHES_DIR}/${HASHES_FILE}`]: JSON.stringify(result.manifest, null, 2) + '\n',
+  };
+
+  for (const [rel, content] of Object.entries(toWrite)) {
+    const abs = join(projectRoot, rel);
+    const dir = dirname(abs);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(abs, content, 'utf-8');
+  }
+
+  // Realize's single-file writeOutput skips empty strings (see
+  // realize/index.ts writeOutput). The orchestrator already wrote
+  // everything it needed.
+  return '';
+}
+
+export default generate;

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

@@ -0,0 +1,57 @@
+/**
+ * package.json generator for ReactAppStarter
+ *
+ * Deliberately does NOT include @specverse/runtime. The promise of
+ * Factory B is that the generated project is standalone — everything
+ * needed to render is emitted as local source.
+ */
+
+export interface PackageJsonGeneratorContext {
+  spec: {
+    metadata?: { name?: string };
+    name?: string;
+  };
+  manifest?: unknown;
+}
+
+export async function generate(context: PackageJsonGeneratorContext): Promise<string> {
+  const appName = context.spec?.metadata?.name ?? context.spec?.name ?? 'specverse-starter-app';
+  const packageName = slugify(appName);
+
+  const pkg = {
+    name: packageName,
+    private: true,
+    version: '0.1.0',
+    type: 'module',
+    scripts: {
+      dev: 'vite',
+      build: 'tsc && vite build',
+      preview: 'vite preview',
+      typecheck: 'tsc --noEmit',
+    },
+    dependencies: {
+      react: '^18.2.0',
+      'react-dom': '^18.2.0',
+      '@tanstack/react-query': '^5.0.0',
+    },
+    devDependencies: {
+      '@types/react': '^18.2.0',
+      '@types/react-dom': '^18.2.0',
+      '@vitejs/plugin-react': '^4.2.0',
+      autoprefixer: '^10.4.20',
+      postcss: '^8.4.47',
+      tailwindcss: '^3.4.13',
+      typescript: '^5.2.0',
+      vite: '^6.0.0',
+    },
+  };
+
+  return JSON.stringify(pkg, null, 2) + '\n';
+}
+
+function slugify(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'specverse-starter-app';
+}