@specverse/engines 4.2.0 → 4.2.2

package/dist/libs/instance-factories/applications/templates/react-starter/use-api-hooks-starter-generator.js

@@ -0,0 +1,95 @@
+function pluralize(s) {
+  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";
+}
+async function generate(context) {
+  const models = Object.keys(context.spec.models ?? {});
+  const importsAndTypes = `/**
+ * useApi \u2014 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} \u2014 \${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) {
+  const plural = pluralize(model);
+  const resource = plural.toLowerCase();
+  const modelLower = model.toLowerCase();
+  return `// \u2500\u2500\u2500 ${model} \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+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}'] }),
+  });
+}`;
+}
+var stdin_default = generate;
+export {
+  stdin_default as default,
+  generate
+};

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

@@ -1,6 +1,7 @@
 import { readFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { extractBelongsToTargets, pluralize as pluralizeShared } from "./belongs-to.js";
 function emitView(context) {
   const skeleton = loadSkeleton(context.view.type);
   const bodyJsx = context.renderBody(context);
@@ -30,12 +31,36 @@ function loadSkeleton(viewType) {
 function buildSubstitutions(context, body) {
   const modelName = context.model.name;
   const pluralModel = pluralize(modelName);
+  const { imports, hooks } = buildBelongsToWiring(context);
   return {
     MODEL_NAME: modelName,
     PLURAL_MODEL: pluralModel,
     PLURAL_LOWER: pluralModel.toLowerCase(),
     SINGULAR_LOWER: modelName.toLowerCase(),
-    BODY: body
+    BODY: body,
+    RELATED_IMPORTS: imports,
+    RELATED_HOOKS: hooks
+  };
+}
+function buildBelongsToWiring(context) {
+  const rels = extractBelongsToTargets(context.model);
+  if (rels.length === 0) return { imports: "", hooks: "" };
+  const hookImportNames = /* @__PURE__ */ new Set();
+  for (const rel of rels) {
+    hookImportNames.add(`use${pluralizeShared(rel.target)}Query`);
+  }
+  const helperImport = context.view.type.toLowerCase() === "form" ? "getEntityDisplayName" : "resolveEntityDisplayName";
+  const importLines = [];
+  importLines.push(
+    `import { ${[...hookImportNames].join(", ")} } from '../hooks/useApi';`
+  );
+  importLines.push(`import { ${helperImport} } from '../lib/entity-display';`);
+  const hookLines = rels.map(
+    (rel) => `  const { data: ${rel.name}Options = [] } = use${pluralizeShared(rel.target)}Query();`
+  );
+  return {
+    imports: importLines.join("\n"),
+    hooks: hookLines.join("\n")
   };
 }
 function applySubstitutions(template, subs) {

package/dist/libs/instance-factories/archived/fastify-prisma.yaml

@@ -0,0 +1,104 @@
+name: FastifyPrismaAPI
+version: "1.0.0"
+category: controller
+description: "Fastify server with Prisma ORM, Zod validation, and JWT authentication"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [fastify, prisma, typescript, rest-api]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "api.rest"
+    - "api.rest.crud"
+    - "api.websocket"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "fastify"
+  orm: "prisma"
+  validation: "zod"
+  authentication: "jwt"
+
+dependencies:
+  runtime:
+    - name: "fastify"
+      version: "^4.24.0"
+    - name: "@fastify/cors"
+      version: "^8.4.0"
+    - name: "@fastify/jwt"
+      version: "^7.2.0"
+    - name: "@fastify/helmet"
+      version: "^11.1.0"
+    - name: "@fastify/rate-limit"
+      version: "^9.0.0"
+    - name: "@prisma/client"
+      version: "^5.5.0"
+    - name: "zod"
+      version: "^3.22.0"
+
+  dev:
+    - name: "prisma"
+      version: "^5.5.0"
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+    - name: "tsx"
+      version: "^4.0.0"
+
+codeTemplates:
+  routes:
+    engine: typescript
+    generator: "libs/instance-factories/backend/templates/fastify/routes-generator.ts"
+    outputPattern: "routes/{controller}.ts"
+
+  services:
+    engine: typescript
+    generator: "libs/instance-factories/backend/templates/prisma/services-generator.ts"
+    outputPattern: "services/{model}.service.ts"
+
+  schema:
+    engine: typescript
+    generator: "libs/instance-factories/backend/templates/prisma/schema-generator.ts"
+    outputPattern: "prisma/schema.prisma"
+
+configuration:
+  server:
+    port: 3000
+    host: "0.0.0.0"
+    trustProxy: true
+    requestIdLogLabel: "reqId"
+    logger:
+      level: "info"
+      prettyPrint: true
+
+  orm:
+    provider: "postgresql"
+    relationMode: "foreignKeys"
+    log: ["query", "error", "warn"]
+
+  middleware:
+    cors:
+      origin: true
+      credentials: true
+    helmet:
+      enabled: true
+    rateLimit:
+      max: 100
+      timeWindow: "1 minute"
+    jwt:
+      secret: "${JWT_SECRET}"
+      sign:
+        expiresIn: "7d"
+
+  validation:
+    stripUnknown: true
+    abortEarly: false

package/dist/libs/instance-factories/cli/README.md

@@ -0,0 +1,43 @@
+# CLI Factory
+
+Generates Commander.js CLI applications from spec command definitions.
+
+## Definition
+
+| File | Description |
+|------|-------------|
+| `commander-js.yaml` | Commander.js v12 CLI with argument parsing, help text, and command routing |
+
+## Generated Output
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `cli-entry-generator` | `backend/src/cli/index.ts` | Main CLI entry point — registers all commands from spec |
+| `command-generator` | `backend/src/cli/commands/{command}.ts` | Individual command files (one per spec command) |
+
+The entry generator reads the spec's `commands` section and registers each as a
+Commander.js command with arguments, flags, and help text. Each command file
+delegates to its corresponding service for business logic.
+
+## Technology
+
+- **Framework**: Commander.js ^12.0.0
+- **Runtime**: Node.js with tsx for development
+- **Language**: TypeScript
+
+## Capabilities
+
+| Provides | Requires |
+|----------|----------|
+| `cli.commands` | `service.controller` |
+| `cli.parser` | |
+| `cli.help` | |
+
+## Spec Integration
+
+Commands are defined in the spec with:
+- `arguments` — positional parameters
+- `flags` — optional switches
+- `returns` — output format
+- `exitCodes` — process exit codes
+- `subcommands` — nested command trees

package/dist/libs/instance-factories/cli/commander-js.yaml

@@ -0,0 +1,55 @@
+name: CommanderJS
+version: "1.0.0"
+category: cli
+description: "Node.js CLI generation using Commander.js"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [cli, commander, node, typescript]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "cli.commands"
+    - "cli.parser"
+    - "cli.help"
+  requires:
+    - "service.controller"
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "commander"
+  version: "^12.0.0"
+
+dependencies:
+  runtime:
+    - name: "commander"
+      version: "^12.0.0"
+
+  dev:
+    - name: "@types/node"
+      version: "^20.8.0"
+    - name: "typescript"
+      version: "^5.2.0"
+    - name: "tsx"
+      version: "^4.0.0"
+
+codeTemplates:
+  cli-entry:
+    engine: typescript
+    generator: "libs/instance-factories/cli/templates/commander/cli-entry-generator.ts"
+    outputPattern: "{backendDir}/src/cli/index.ts"
+
+  cli-commands:
+    engine: typescript
+    generator: "libs/instance-factories/cli/templates/commander/command-generator.ts"
+    outputPattern: "{backendDir}/src/cli/commands/{command}.ts"
+
+configuration:
+  outputStructure: "monorepo"
+  backendDir: "backend"

package/dist/libs/instance-factories/cli/templates/commander/command-generator.js

@@ -505,8 +505,56 @@ import { fileURLToPath } from 'url';`,
         }
 
         copyDir(templateDir, destDir);
+
+        // If the copied template didn't ship a specs/main.specly, load
+        // the canonical default spec from @specverse/engines/assets \u2014
+        // same file app-demo's Server Manager "new spec" action uses,
+        // so both entry points start a user on the same footing. The
+        // template can opt out of this by shipping its own spec.
+        const specDestPath = join(destDir, 'specs', 'main.specly');
+        if (!existsSync(specDestPath)) {
+          try {
+            const { createRequire } = await import('module');
+            const require = createRequire(import.meta.url);
+            const enginesPkg = require.resolve('@specverse/engines/package.json');
+            const canonicalSpec = join(
+              dirname(enginesPkg),
+              'assets', 'templates', 'default', 'specs', 'main.specly'
+            );
+            if (existsSync(canonicalSpec)) {
+              let content = readFileSync(canonicalSpec, 'utf8');
+              for (const [key, val] of Object.entries(vars)) {
+                content = content.split(key).join(val);
+              }
+              mkdirSync(join(destDir, 'specs'), { recursive: true });
+              writeFileSync(specDestPath, content);
+            }
+          } catch { /* engines not installed or template missing \u2014 proceed */ }
+        }
+
+        // --static: flip any ReactAppRuntime mappings in the copied
+        // manifests to ReactAppStarter so the user gets standalone-starter
+        // output on first \`spv realize\` without having to re-pass the
+        // flag. Same semantic as \`spv realize --static\` \u2014 just applied
+        // at init time. Idempotent; no-op for templates without a frontend.
+        if (options.static) {
+          const manifestsDir = join(destDir, 'manifests');
+          if (existsSync(manifestsDir)) {
+            for (const f of readdirSync(manifestsDir)) {
+              if (!f.endsWith('.yaml') && !f.endsWith('.yml')) continue;
+              const p = join(manifestsDir, f);
+              const before = readFileSync(p, 'utf8');
+              const after = before.replace(
+                /instanceFactory:\\s*["']?ReactAppRuntime["']?/g,
+                'instanceFactory: "ReactAppStarter"'
+              );
+              if (after !== before) writeFileSync(p, after, 'utf8');
+            }
+          }
+        }
+
         console.log('Project created: ' + destDir);
-        console.log('Template: ' + templateName);
+        console.log('Template: ' + templateName + (options.static ? ' (static / ReactAppStarter)' : ''));
         console.log('');
 
         // Build the "Next steps" hint from the actual scripts the

package/dist/libs/instance-factories/communication/README.md

@@ -0,0 +1,47 @@
+# Communication Factory
+
+Event-driven messaging infrastructure with publisher/subscriber generation.
+
+## Definitions
+
+| File | Description |
+|------|-------------|
+| `event-emitter.yaml` | In-memory event bus using EventEmitter3 (development/testing) |
+| `rabbitmq-events.yaml` | RabbitMQ AMQP bus for production pub/sub messaging |
+
+## Generated Output
+
+### EventEmitter (`eventemitter/`)
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `bus-generator` | `src/events/eventBus.ts` | Singleton event bus with typed event names |
+| `publisher-generator` | `src/events/publishers/{event}Publisher.ts` | Per-event publisher (one per spec event) |
+| `subscriber-generator` | `src/events/subscribers/{event}Subscriber.ts` | Per-event subscriber with handler logic |
+
+### RabbitMQ (`rabbitmq/` — defined, templates pending)
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `publisher-generator` | `src/events/publishers/{event}Publisher.ts` | AMQP publisher with confirms |
+| `subscriber-generator` | `src/events/subscribers/{event}Subscriber.ts` | AMQP consumer with ack/nack |
+| `connection-generator` | `src/events/connection.ts` | RabbitMQ connection management |
+
+## Technology
+
+- **EventEmitter**: eventemitter3 ^5.0.0 (zero-dependency, in-process)
+- **RabbitMQ**: amqplib ^0.10.3 (topic exchange, durable queues, prefetch)
+
+## Capabilities
+
+| Provides | Requires |
+|----------|----------|
+| `messaging.pubsub` | (none) |
+| `messaging.events` | |
+| `messaging.inmemory` (EventEmitter) | |
+| `messaging.queue` (RabbitMQ) | |
+
+## Configuration
+
+EventEmitter: `maxListeners: 100`, `captureRejections: true`
+RabbitMQ: topic exchange, durable queues, prefetch 10, persistent messages, confirm-select

package/dist/libs/instance-factories/communication/event-emitter.yaml

@@ -0,0 +1,60 @@
+name: EventEmitter
+version: "2.0.0"
+category: communication
+description: "Typed in-memory event bus with WebSocket bridge for real-time frontend updates"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [events, in-memory, pubsub, websocket, eventemitter, development]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "messaging.pubsub"
+    - "messaging.events"
+    - "messaging.inmemory"
+    - "messaging.websocket"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "eventemitter3"
+  version: "^5.0.0"
+
+dependencies:
+  runtime:
+    - name: "eventemitter3"
+      version: "^5.0.0"
+    - name: "@fastify/websocket"
+      version: "^11.0.0"
+
+  dev:
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  types:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/eventemitter/types-generator.ts"
+    outputPattern: "{backendDir}/src/events/event-types.ts"
+
+  bus:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/eventemitter/bus-generator.ts"
+    outputPattern: "{backendDir}/src/events/eventBus.ts"
+
+  websocket:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/eventemitter/websocket-bridge-generator.ts"
+    outputPattern: "{backendDir}/src/events/websocket-bridge.ts"
+
+configuration:
+  maxListeners: 100
+  captureRejections: true
+  errorHandling: "log"
+  websocket: true

package/dist/libs/instance-factories/communication/rabbitmq-events.yaml

@@ -0,0 +1,87 @@
+name: RabbitMQEvents
+version: "1.0.0"
+category: communication
+description: "RabbitMQ event bus for pub/sub messaging and event-driven architecture"
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [rabbitmq, events, messaging, pubsub, amqp]
+
+compatibility:
+  specverse: ">=3.3.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "messaging.pubsub"
+    - "messaging.events"
+    - "messaging.queue"
+  requires: []
+
+technology:
+  runtime: "node"
+  language: "typescript"
+  framework: "amqplib"
+  version: "^0.10.3"
+
+dependencies:
+  runtime:
+    - name: "amqplib"
+      version: "^0.10.3"
+    - name: "uuid"
+      version: "^9.0.0"
+
+  dev:
+    - name: "@types/amqplib"
+      version: "^0.10.4"
+    - name: "@types/uuid"
+      version: "^9.0.0"
+    - name: "typescript"
+      version: "^5.2.0"
+
+codeTemplates:
+  publisher:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/rabbitmq/publisher-generator.ts"
+    outputPattern: "src/events/publishers/{event}Publisher.ts"
+
+  subscriber:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/rabbitmq/subscriber-generator.ts"
+    outputPattern: "src/events/subscribers/{event}Subscriber.ts"
+
+  connection:
+    engine: typescript
+    generator: "libs/instance-factories/communication/templates/rabbitmq/connection-generator.ts"
+    outputPattern: "src/events/connection.ts"
+
+configuration:
+  connection:
+    protocol: "amqp"
+    hostname: "localhost"
+    port: 5672
+    username: "guest"
+    password: "guest"
+    vhost: "/"
+    heartbeat: 60
+
+  exchange:
+    type: "topic"
+    durable: true
+    autoDelete: false
+
+  queue:
+    durable: true
+    exclusive: false
+    autoDelete: false
+
+  publishing:
+    persistent: true
+    mandatory: true
+    confirmSelect: true
+
+  consuming:
+    prefetch: 10
+    noAck: false
+    exclusive: false

package/dist/libs/instance-factories/controllers/README.md

@@ -0,0 +1,42 @@
+# Controllers Factory
+
+Fastify REST API route handlers and server bootstrap generation.
+
+## Definition
+
+| File | Description |
+|------|-------------|
+| `fastify.yaml` | Fastify v4 REST API server with CORS, Helmet, and rate limiting |
+
+## Generated Output
+
+| Generator | Output | Purpose |
+|-----------|--------|---------|
+| `routes-generator` | `backend/src/routes/{controller}.ts` | Per-model route handler with CRUD endpoints |
+| `meta-routes-generator` | `backend/src/routes/MetaRoutes.ts` | Meta API for spec/view metadata (serves frontend) |
+| `server-generator` | `backend/src/server.ts` | Server bootstrap — registers all model routes |
+
+The routes generator reads each controller from the spec and creates Fastify route
+handlers. The server generator auto-imports and registers all model route files.
+Meta routes expose spec and view metadata for the view-renderer architecture.
+
+## Technology
+
+- **Framework**: Fastify ^4.24.0
+- **Middleware**: @fastify/cors, @fastify/helmet, @fastify/rate-limit
+- **Language**: TypeScript with tsx for development
+
+## Capabilities
+
+| Provides | Requires |
+|----------|----------|
+| `api.rest` | `storage.database` |
+| `api.rest.crud` | `validation.runtime` |
+| `api.websocket` | |
+
+## Configuration
+
+- Server: port 3000, host 0.0.0.0, trust proxy, structured logging
+- CORS: origin true, credentials true
+- Rate limit: 100 requests per minute
+- Scripts: `dev` (tsx watch), `start` (node dist)