@specverse/engines 4.2.1 → 4.3.0

package/dist/libs/instance-factories/applications/templates/react-starter/operation-emitters.js

@@ -0,0 +1,470 @@
+function emitFieldInput() {
+  return `/**
+ * FieldInput \u2014 type-aware input component used by OperationExecutor.
+ *
+ * Inlined into this project by @specverse/realize (ReactAppStarter).
+ * Edit freely. Ported from app-demo's FieldInput.
+ *
+ * Renders the right input for a parameter type:
+ *   - UUID ending in Id \u2192 entity dropdown via EntitySelect
+ *   - Boolean \u2192 checkbox (or select in compact mode)
+ *   - Integer/Number/Decimal \u2192 number input
+ *   - DateTime/Date \u2192 native picker
+ *   - Email \u2192 email input
+ *   - Text (multiline) \u2192 textarea
+ *   - default \u2192 text input
+ */
+import { useState, useEffect } from 'react';
+import { getEntityDisplayName } from './entity-display';
+
+const API_BASE = import.meta.env.VITE_API_BASE_URL || '';
+
+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';
+}
+
+function humanizeFieldName(name: string): string {
+  return name
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, c => c.toUpperCase())
+    .trim();
+}
+
+interface FieldInputProps {
+  name: string;
+  typeStr: string;
+  value: any;
+  onChange: (value: any) => void;
+  required?: boolean;
+  disabled?: boolean;
+  /** Compact mode for inline use (smaller padding, no label). */
+  compact?: boolean;
+}
+
+const inputClass = (compact: boolean) => compact
+  ? 'w-full px-2 py-1 text-xs bg-white dark:bg-gray-800 border border-gray-300 dark:border-gray-600 rounded focus:outline-none focus:ring-1 focus:ring-blue-500'
+  : 'w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded text-sm bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-2 focus:ring-blue-500 disabled:bg-gray-100 dark:disabled:bg-gray-800 disabled:cursor-not-allowed';
+
+export function FieldInput({ name, typeStr, value, onChange, required, disabled, compact = false }: FieldInputProps) {
+  const type = typeStr.toLowerCase();
+
+  if (type.includes('bool')) {
+    return compact ? (
+      <select
+        value={value ?? ''}
+        onChange={e => onChange(e.target.value === 'true')}
+        disabled={disabled}
+        className={inputClass(compact)}
+      >
+        <option value="">Select...</option>
+        <option value="true">true</option>
+        <option value="false">false</option>
+      </select>
+    ) : (
+      <div className="flex items-center pt-2">
+        <input
+          type="checkbox"
+          checked={!!value}
+          onChange={e => onChange(e.target.checked)}
+          disabled={disabled}
+          className="h-4 w-4 text-blue-600 border-gray-300 dark:border-gray-600 rounded focus:ring-blue-500"
+        />
+        <span className="ml-2 text-sm text-gray-600 dark:text-gray-300">
+          {value ? 'Yes' : 'No'}
+        </span>
+      </div>
+    );
+  }
+
+  if (type.includes('int') || type.includes('number') || type.includes('decimal')) {
+    return (
+      <input
+        type="number"
+        step={type.includes('decimal') ? '0.01' : '1'}
+        value={value ?? ''}
+        onChange={e => onChange(type.includes('int') ? parseInt(e.target.value) || 0 : parseFloat(e.target.value) || 0)}
+        disabled={disabled}
+        required={required}
+        className={inputClass(compact)}
+      />
+    );
+  }
+
+  if (type.includes('datetime')) {
+    return (
+      <input
+        type="datetime-local"
+        value={value ? new Date(value).toISOString().slice(0, 16) : ''}
+        onChange={e => onChange(e.target.value ? new Date(e.target.value).toISOString() : '')}
+        disabled={disabled}
+        required={required}
+        className={inputClass(compact)}
+      />
+    );
+  }
+
+  if (type.includes('date')) {
+    return (
+      <input
+        type="date"
+        value={value ? new Date(value).toISOString().slice(0, 10) : ''}
+        onChange={e => onChange(e.target.value ? new Date(e.target.value).toISOString() : '')}
+        disabled={disabled}
+        required={required}
+        className={inputClass(compact)}
+      />
+    );
+  }
+
+  if (type.includes('email')) {
+    return (
+      <input
+        type="email"
+        value={value ?? ''}
+        onChange={e => onChange(e.target.value)}
+        disabled={disabled}
+        required={required}
+        placeholder={humanizeFieldName(name)}
+        className={inputClass(compact)}
+      />
+    );
+  }
+
+  if (type === 'text') {
+    return (
+      <textarea
+        value={value ?? ''}
+        onChange={e => onChange(e.target.value)}
+        disabled={disabled}
+        required={required}
+        rows={compact ? 2 : 3}
+        placeholder={humanizeFieldName(name)}
+        className={\`\${inputClass(compact)} resize-none\`}
+      />
+    );
+  }
+
+  return (
+    <input
+      type="text"
+      value={value ?? ''}
+      onChange={e => onChange(e.target.value)}
+      disabled={disabled}
+      required={required}
+      placeholder={\`\${humanizeFieldName(name)}\${typeStr ? \` (\${typeStr})\` : ''}\`}
+      className={inputClass(compact)}
+    />
+  );
+}
+
+/**
+ * EntitySelect \u2014 dropdown of existing entities, for UUID parameters
+ * that reference a model. Fetches \`GET /api/{resource}\` (static REST
+ * convention) and renders each entity by its display name.
+ */
+interface EntitySelectProps {
+  modelName: string;
+  value: string;
+  onChange: (value: string) => void;
+  compact?: boolean;
+  /** Filter entities by a foreign key value, e.g. { categoryId: 'abc-123' }.
+   *  Used for cascading pickers where a second param depends on the first. */
+  filterBy?: Record<string, string>;
+}
+
+export function EntitySelect({ modelName, value, onChange, compact = false, filterBy }: EntitySelectProps) {
+  const [allEntities, setAllEntities] = useState<any[]>([]);
+  const resource = pluralize(modelName).toLowerCase();
+
+  useEffect(() => {
+    fetch(\`\${API_BASE}/api/\${resource}\`)
+      .then(r => r.json())
+      .then(data => setAllEntities(Array.isArray(data) ? data : []))
+      .catch(() => setAllEntities([]));
+  }, [resource]);
+
+  const entities = filterBy
+    ? allEntities.filter(e => {
+        for (const [fk, fkValue] of Object.entries(filterBy)) {
+          if (!fkValue) continue;
+          if (!(fk in e)) continue;
+          if (e[fk] !== fkValue) return false;
+        }
+        return true;
+      })
+    : allEntities;
+
+  return (
+    <select
+      value={value || ''}
+      onChange={e => onChange(e.target.value)}
+      className={inputClass(compact)}
+    >
+      <option value="">
+        Select {modelName}...{filterBy && Object.values(filterBy).some(v => v) ? \` (\${entities.length} matching)\` : ''}
+      </option>
+      {entities.map(entity => {
+        const id = entity.id;
+        return (
+          <option key={id} value={id}>
+            {getEntityDisplayName(entity)}{id ? \` (\${String(id).slice(0, 8)}...)\` : ''}
+          </option>
+        );
+      })}
+    </select>
+  );
+}
+`;
+}
+function emitOperationExecutor() {
+  return `/**
+ * OperationExecutor \u2014 run a controller command or service operation
+ * against the backend. Renders a parameter form, an Execute button,
+ * and the result/error beneath.
+ *
+ * Inlined into this project by @specverse/realize (ReactAppStarter).
+ * Edit freely. Ported from app-demo's OperationExecutor.
+ *
+ * For source='service' ops: POST /api/services/{serviceName}/{operationName}
+ * For source='controller' ops: POST /api/{resource}/{operationName}, where
+ *   resource is the pluralized-lowercase form of the controller's managed
+ *   model (ControllerName minus 'Controller' suffix).
+ */
+import { useState, useMemo } from 'react';
+import { FieldInput, EntitySelect } from './FieldInput';
+import { OperationResultView } from './OperationResultView';
+import { Play } from 'lucide-react';
+
+const API_BASE = import.meta.env.VITE_API_BASE_URL || '';
+
+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';
+}
+
+interface OperationExecutorProps {
+  /** The service (source='service') or controller (source='controller') name. */
+  serviceName: string;
+  operationName: string;
+  /** Parameter declarations from the spec. Supports both
+   *  \`{ name: { type: 'String' } }\` and \`{ name: 'String' }\` shapes. */
+  parameters?: Record<string, any>;
+  /** Optional; currently unused but kept for forward compat with
+   *  app-demo where requires gates the run. */
+  requires?: string[];
+  source?: 'service' | 'controller';
+}
+
+export function OperationExecutor({
+  serviceName,
+  operationName,
+  parameters,
+  requires: _requires,
+  source = 'service',
+}: OperationExecutorProps) {
+  const [params, setParams] = useState<Record<string, any>>({});
+  const [loading, setLoading] = useState(false);
+  const [result, setResult] = useState<any>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const paramDefs = useMemo(() => {
+    if (!parameters) return [];
+    const entries: Array<[string, any]> = Array.isArray(parameters)
+      ? parameters.map((p: any) => [p.name, p])
+      : Object.entries(parameters);
+    if (entries.length === 0) return [];
+
+    return entries.map(([name, def]) => {
+      const typeStr = typeof def === 'string' ? def : def?.type || '';
+      const isUuid = typeStr.toLowerCase().includes('uuid');
+      let refModel: string | null = null;
+      if (isUuid && name.endsWith('Id')) {
+        const base = name.slice(0, -2);
+        refModel = base.charAt(0).toUpperCase() + base.slice(1);
+      }
+      return { name, type: typeStr, isUuid, refModel };
+    });
+  }, [parameters]);
+
+  const execute = async () => {
+    setLoading(true);
+    setError(null);
+    setResult(null);
+    try {
+      let url: string;
+      if (source === 'controller') {
+        // ControllerName \u2192 resource-plural-lowercase (PostController \u2192 posts)
+        const modelName = serviceName.replace(/Controller$/, '');
+        const resource = pluralize(modelName).toLowerCase();
+        url = \`\${API_BASE}/api/\${resource}/\${operationName}\`;
+      } else {
+        url = \`\${API_BASE}/api/services/\${serviceName}/\${operationName}\`;
+      }
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(params),
+      });
+      const data = await res.json();
+      setResult(data);
+      if (!res.ok) {
+        setError(data?.message || data?.error || \`\${res.status} \${res.statusText}\`);
+      } else if (data && data.success === false) {
+        setError(data.error?.message || 'Operation failed');
+      }
+    } catch (err: any) {
+      setError(err?.message ?? String(err));
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="mt-3 pt-3 border-t border-gray-200 dark:border-gray-600 space-y-2">
+      {paramDefs.length > 0 ? (
+        paramDefs.map(param => {
+          // Cascading filter: if this param's model has a belongsTo to another
+          // already-filled param's model, filter by it.
+          let filterBy: Record<string, string> | undefined;
+          if (param.refModel) {
+            for (const other of paramDefs) {
+              if (other === param || !other.refModel) continue;
+              const fk = other.refModel.charAt(0).toLowerCase() + other.refModel.slice(1) + 'Id';
+              if (params[other.name]) {
+                filterBy = { ...filterBy, [fk]: params[other.name] };
+              }
+            }
+          }
+          return (
+            <div key={param.name} className="flex items-center gap-2">
+              <label
+                className="text-xs text-gray-500 dark:text-gray-400 w-24 flex-shrink-0 truncate"
+                title={param.name}
+              >
+                {param.name}
+              </label>
+              {param.refModel ? (
+                <EntitySelect
+                  modelName={param.refModel}
+                  value={params[param.name] || ''}
+                  onChange={v => setParams(prev => ({ ...prev, [param.name]: v }))}
+                  filterBy={filterBy}
+                  compact
+                />
+              ) : (
+                <FieldInput
+                  name={param.name}
+                  typeStr={param.type}
+                  value={params[param.name]}
+                  onChange={v => setParams(prev => ({ ...prev, [param.name]: v }))}
+                  compact
+                />
+              )}
+            </div>
+          );
+        })
+      ) : (
+        <p className="text-xs text-gray-400 italic">No parameters defined</p>
+      )}
+
+      <button
+        onClick={execute}
+        disabled={loading}
+        className="w-full px-3 py-1.5 bg-blue-600 hover:bg-blue-700 text-white text-xs font-medium rounded flex items-center justify-center gap-1 disabled:opacity-50"
+      >
+        <Play className="w-3 h-3" />
+        {loading ? 'Executing...' : \`Execute \${operationName}\`}
+      </button>
+
+      {error && !result && (
+        <pre className="p-2 text-xs text-red-400 bg-red-50 dark:bg-red-900/20 rounded overflow-x-auto">
+          {error}
+        </pre>
+      )}
+      {result && <OperationResultView result={result} />}
+    </div>
+  );
+}
+`;
+}
+function emitOperationResultView() {
+  return `/**
+ * OperationResultView \u2014 formatted display of an operation's result.
+ *
+ * Inlined into this project by @specverse/realize (ReactAppStarter).
+ * Edit freely. Ported from app-demo's OperationResultView.
+ *
+ * Handles three shapes:
+ *   - Success with data \u2192 JSON pretty-print
+ *   - Success without data \u2192 "Operation succeeded" banner
+ *   - Error { success: false, error: ... } \u2192 error banner + details
+ *   - Unexpected \u2192 raw JSON
+ */
+import { CheckCircle, XCircle } from 'lucide-react';
+
+interface OperationResultViewProps {
+  result: any;
+}
+
+function JsonDisplay({ value }: { value: any }) {
+  return (
+    <pre className="p-3 text-xs bg-gray-50 dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded overflow-x-auto text-gray-900 dark:text-gray-100">
+      {JSON.stringify(value, null, 2)}
+    </pre>
+  );
+}
+
+export function OperationResultView({ result }: OperationResultViewProps) {
+  // Explicit error envelope: { success: false, error: ... }
+  if (result && typeof result === 'object' && result.success === false) {
+    const errMsg =
+      (typeof result.error === 'object' ? result.error?.message : result.error) ||
+      'Operation failed';
+    return (
+      <div className="space-y-2">
+        <div className="flex items-start gap-2 p-2 rounded bg-red-50 dark:bg-red-900/20 text-red-700 dark:text-red-300 text-xs">
+          <XCircle className="w-4 h-4 flex-shrink-0 mt-0.5" />
+          <div>
+            <div className="font-medium">Operation failed</div>
+            <div className="mt-1">{errMsg}</div>
+          </div>
+        </div>
+        {result.error && typeof result.error === 'object' && <JsonDisplay value={result.error} />}
+      </div>
+    );
+  }
+
+  // Explicit success envelope: { success: true, data?: ... }
+  if (result && typeof result === 'object' && result.success === true) {
+    return (
+      <div className="space-y-2">
+        <div className="flex items-center gap-2 p-2 rounded bg-green-50 dark:bg-green-900/20 text-green-700 dark:text-green-300 text-xs">
+          <CheckCircle className="w-4 h-4 flex-shrink-0" />
+          <span className="font-medium">Operation succeeded</span>
+        </div>
+        {result.data !== undefined && <JsonDisplay value={result.data} />}
+      </div>
+    );
+  }
+
+  // No envelope \u2014 just show whatever came back (most REST endpoints).
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center gap-2 p-2 rounded bg-green-50 dark:bg-green-900/20 text-green-700 dark:text-green-300 text-xs">
+        <CheckCircle className="w-4 h-4 flex-shrink-0" />
+        <span className="font-medium">Operation completed</span>
+      </div>
+      {result !== undefined && result !== null && <JsonDisplay value={result} />}
+    </div>
+  );
+}
+`;
+}
+export {
+  emitFieldInput,
+  emitOperationExecutor,
+  emitOperationResultView
+};

package/dist/libs/instance-factories/applications/templates/react-starter/operation-view-generator.js

@@ -0,0 +1,136 @@
+const STANDARD_OPS = /* @__PURE__ */ new Set([
+  "create",
+  "retrieve",
+  "retrieve_many",
+  "update",
+  "delete",
+  "validate",
+  "evolve",
+  "list",
+  "query",
+  "get",
+  "attachProfile",
+  "detachProfile",
+  "hasProfile",
+  "handleChildAdded",
+  "handleChildRemoved",
+  "validateRelationshipIntegrity",
+  "repairRelationshipIntegrity"
+]);
+function normalizeParameters(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const out = {};
+  for (const [name, def] of Object.entries(raw)) {
+    let type;
+    if (typeof def === "string") {
+      type = def;
+    } else if (def && typeof def === "object" && "type" in def && typeof def.type === "string") {
+      type = def.type;
+    } else {
+      type = "String";
+    }
+    out[name] = type.split(/\s+/)[0] || "String";
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function collectOperationViews(spec) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const controllers = spec.controllers ?? {};
+  for (const [ctlName, ctl] of Object.entries(controllers)) {
+    const ops = ctl?.operations ?? ctl?.commands ?? {};
+    for (const [opName, op] of Object.entries(ops)) {
+      if (STANDARD_OPS.has(opName)) continue;
+      const viewName = capitalize(opName) + "View";
+      if (seen.has(viewName)) continue;
+      seen.add(viewName);
+      out.push({
+        viewName,
+        label: humanize(opName),
+        serviceName: ctlName,
+        operationName: opName,
+        parameters: normalizeParameters(op?.parameters ?? op?.params),
+        requires: op?.requires,
+        returns: op?.returns,
+        source: "controller"
+      });
+    }
+  }
+  const services = spec.services ?? {};
+  for (const [svcName, svc] of Object.entries(services)) {
+    const rawOps = svc?.operations;
+    const opEntries = Array.isArray(rawOps) ? rawOps.map((o) => [o.name, o]) : Object.entries(rawOps ?? {});
+    for (const [opName, op] of opEntries) {
+      if (!opName) continue;
+      if (STANDARD_OPS.has(opName)) continue;
+      const viewName = capitalize(opName) + "View";
+      if (seen.has(viewName)) continue;
+      seen.add(viewName);
+      out.push({
+        viewName,
+        label: humanize(opName),
+        serviceName: svcName,
+        operationName: opName,
+        parameters: normalizeParameters(op?.parameters ?? op?.params),
+        requires: op?.requires,
+        returns: op?.returns,
+        source: "service"
+      });
+    }
+  }
+  return out;
+}
+function emitOperationView(desc) {
+  const paramsJson = desc.parameters ? JSON.stringify(desc.parameters, null, 2).replace(/\n/g, "\n        ") : "undefined";
+  const requiresJson = desc.requires ? JSON.stringify(desc.requires) : "undefined";
+  const returnsPill = desc.returns ? `
+        <span className="text-xs px-2 py-0.5 bg-gray-200 dark:bg-gray-700 text-gray-600 dark:text-gray-300 rounded font-mono">
+          \u2192 ${escapeJsx(desc.returns)}
+        </span>` : "";
+  return `/**
+ * ${desc.viewName} \u2014 generated by @specverse/realize (ReactAppStarter)
+ *
+ * Auto-generated operation view for ${desc.source} ${desc.serviceName}.${desc.operationName}.
+ * Safe to edit; the generator will not overwrite a hand-edited file
+ * (content-hashing in .specverse-gen/hashes.json).
+ */
+import { OperationExecutor } from '../lib/OperationExecutor';
+
+export function ${desc.viewName}() {
+  return (
+    <div className="p-6 space-y-4">
+      <div className="flex items-center gap-2">
+        <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100">
+          ${escapeJsx(desc.label)}
+        </h2>${returnsPill}
+      </div>
+      <p className="text-sm text-gray-500 dark:text-gray-400">
+        Execute ${escapeJsx(desc.serviceName)}.${escapeJsx(desc.operationName)}
+      </p>
+      <div className="max-w-lg">
+        <OperationExecutor
+          serviceName="${desc.serviceName}"
+          operationName="${desc.operationName}"
+          parameters={${paramsJson}}
+          requires={${requiresJson}}
+          source="${desc.source}"
+        />
+      </div>
+    </div>
+  );
+}
+`;
+}
+function capitalize(s) {
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+function humanize(s) {
+  return s.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase()).trim();
+}
+function escapeJsx(s) {
+  return s.replace(/[<>&]/g, (ch) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;" })[ch]);
+}
+export {
+  collectOperationViews,
+  emitOperationView
+};

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

@@ -15,7 +15,8 @@ async function generate(context) {
     dependencies: {
       react: "^18.2.0",
       "react-dom": "^18.2.0",
-      "@tanstack/react-query": "^5.0.0"
+      "@tanstack/react-query": "^5.0.0",
+      "lucide-react": "^0.400.0"
     },
     devDependencies: {
       "@types/react": "^18.2.0",